BigTime's client api provides access to the list of clients that a user would have rights to see if they were logged into the system directly.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /client?{ShowInactive=true} HTTP RESPONSE: (array of client objects ("basic" view -- see below for details)
You can use a simple GET request to pull the details associated with a single entry. Note that the BASIC view fields will be returned by default. You should also note that a user cannot pull client data for an entity they are not permitted to view in the BigTime program. This can often become a problem when back-end services are using the api without system-wide permissions.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /client/detail/{systemid}?View={Detailed/Basic} HTTP RESPONSE: (array of client objects -- see below for details)
Note that only the fields listed in the Update view (below) should be included in your post to this url. Any other data will be ignored. BigTime doesn't care about the order in which field data is posted, and none of the fields are case sensitive. Note that any validation errors will return a 400 error, and an invalid permission will return a 405 (eg - attempting to create a client when you don't have that right).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP Post: /client/detail POST CONTENT: {"Nm": "My Test Client", "ClientId": "TEST-1"} ** You can include ANY of the Update fields below. HTTP RESPONSE: (updated ClientDetail object -- see below for details)
Note that only the fields listed in the Update views (below) should be included in your post to this url. Any other data will be ignored. Note again, validation errors will return a 400 error, and an invalid permission will return a 405.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP Post: /client/detail/{sid} POST CONTENT: {"SystemId": "{sid}", "Nm": "My Test Client", "ClientId": "TEST-1"} ** You can include ANY of the Update fields below. However - you cannot "zero-out" or remove any of the required (*) fields. HTTP RESPONSE: (updated ClientDetail object -- see below for details)
For each of the operations listed above, you will post or "get" one or more client objects. The list below is a complete catalog of fields available through the api (including the views within which those fields are found). Take special note of the Update views. Required fields are flagged with an "*" character.
Field | Type | Description | View(s) |
---|---|---|---|
SystemId | Integer | Unique SID code for this record. Note that this value is an attribute on the main Contact object if you are downloading xml. | Basic, Detail, Update* |
Nm | String | Short/standard name for the client | Basic, Detail, Update |
LegalNm | String | Legal name (eg - full name used on invoices and estimates) | Basic, Detail, Update |
ClientId | String | Unique acount number for this client (often used by BigTime to generate unique account numbers for projects). | Basic, Detail, Update |
Address | String | Street address (can be multi-line) | Basic, Detail, Update |
City | String | Basic, Detail, Update | |
State | String | State, Province or county (depending on the address' country of origin) | Basic, Detail, Update |
Zip | String | Postal code | Basic, Detail, Update |
Country | String | Country of origin. | Basic, Detail, Update |
FullAddress | String | Useful for display: the full address (with line breaks and including the address, csz and country). | Basic |
MainPH | String | Main phone number for the client (note that each project's contact can also have a phone number, mobile phone and fax). | Basic, Detail, Update |
MainFX | String | Main fax number for the client (note that each project's contact can also have a phone number, mobile phone and fax). | Basic, Detail, Update |
Notes | String | Basic, Detail, Update |