BigTime's project api provides access to the list of projects 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: /project?{ShowInactive=true}
HTTP RESPONSE: (array of Project 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 project 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.
For the DETAIL view, If you pass TRUE to ShowAllContacts, then all of the project's OTHER contacts will be returned. If that value is left FALSE (default), then only the primary and billing contacts are returned.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/detail/{systemid}?View={Detailed/Basic}&{ShowAllContacts=True/False}
HTTP RESPONSE: (array of Projects 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 project when you don't have that right).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post: /project/detail
POST CONTENT: {Nm: "My Test Project,
ProjectCode: "TEST-1"}
You can include ANY of the Update fields below,
but you MUST include the required (*) fields.
HTTP RESPONSE: (updated ProjectDetail object -- 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 project when you don't have that right). The template id must be greater than zero.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post: /project/DetailWithTemplateId
POST CONTENT: {TemplateID: "123"}
HTTP RESPONSE: (updated ProjectDetail 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: /project/detail/{sid}
POST CONTENT: {Nm: "My Test Project,
ProjectCode: "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 ProjectDetail object -- see below for details)
Note that the API will not let you delete a project that has transaction data attached to it. Run an update and mark that project as INACTIVE instead.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE: /project/detail/{sid}
HTTP RESPONSE: 200 is a successful delete.
You can also use this API to interact with a project's contacts. Supported actions are described below.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /Project/Contacts
HTTP RESPONSE: array of Contact 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 project 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.
If you pass TRUE to ShowAll, then all of the linked project records (see below) to this contact will be returned. If that value is left FALSE (default), then at most 50 linked projects will be returned.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/contact/{SystemId}?ProjectSid={ProjectSID}&ShowAll=True/False
HTTP RESPONSE: Contact object ("basic" view -- 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 project when you don't have that right).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post: /project/Contact/{SystemId}
POST CONTENT: {ProjectSid: {ProjectSid},
FName: "My Test Name"}
You can include ANY of the Update fields below,
but you MUST include the required (*) fields.
HTTP RESPONSE: updated Contact object ("basic" view -- 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: /project/contact/{SystemId}
POST CONTENT: {ProjectSid: {ProjectSid},
FName: "My Test Name"}
** You can include ANY of the Update fields below.
However - you cannot "zero-out" or remove any of the
required (*) fields.
HTTP RESPONSE: updated Contact object ("basic" view -- see below for details)
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE: /project/Contact/{SystemId}?ProjectSid={ProjectSID}
HTTP RESPONSE: 200 is a successful delete.
You can also use this API to interact with a project's team. Supported actions are described below.
You can use a GET request to pull the list of team members for a specific project. Note that a user cannot pull project 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. No additional parameters are required/supported.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/team/{sid}
HTTP RESPONSE: (array of Project Team Member objects -- see below for details)
You can use a POST request to add, delete, or update an existing project's team. (This will not affect staff teams). To do this, POST to this URL with the project SID and a JSON array of Project Team Member objects. Your project's team will be set according to the JSON array passed to this URL. 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: /project/team/{sid}
POST CONTENT:
[
{
"StaffSID": 12345,
"ContactRole": 6789,
"TeamLead": "TRUE"
},
{
"StaffSID": 4566,
"ContactRole": 69789,
"TeamLead": "FALSE"
},
...
]
HTTP RESPONSE: JSON with success of True or False.
You can also use this API to interact with a project's staff teams. Supported actions are described below.
You can use a GET request to pull the list of staff teams for a specific project. Note that a user cannot pull project 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. No additional parameters are required/supported.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/staffTeams/{sid}
HTTP RESPONSE: (array of Staff Team objects -- see below for details)
You can use a POST request to add, delete, or update an existing project's staff teams. (This will only affect staff teams). To do this, POST to this URL with the project SID and a JSON array of Project Staff Team SIDs. Your project's staff teams will be set according to the JSON array passed to this URL. 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: /project/staffTeams/{sid}
POST CONTENT:[TeamID, TeamID...]
HTTP RESPONSE: JSON with success of True or False.
This section of the API is concerned with project activities.
This endpoint is used to fetch the activities attached to a project in BigTime.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/Activity?projectId={projectId}&showCompleted={true/false/?}startDate={Date?}&endDate={Date?}
HTTP STATUS: 200 Success.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.
HTTP RESPONSE:
{
"ActivityId": long,
"StaffSid": long?,
"ProjectSid": long?,
"TaskSid": long?,
"ActivityType": long,
"ActivityTypeName": string,
"EventType": long?,
"EventTypeName": string,
"Dt": date?,
"IsUnread": bool,
"IsCompleted": bool,
"Nt": string,
"Data": string,
"CreatedDt": date,
"CreatedBy": long,
"EMailId": string,
"EMailStatus": long?,
"EMailStatusName": string,
"NoticeMessage": {
"Body": string,
"LinkText": string,
"href": string,
"NoticeType": string,
"CategoryType": string,
"Subject": string,
"NoticeSettings": string,
},
"Staff_Nm": string,
"Project_Nm": string,
"Client_Sid": long,
"Client_Nm": string
}
This endpoint is used to create activities in the BigTime system.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST: /project/activity
HTTP REQUEST:
{
"ProjectSid": long,
"StaffSid": long?,
"TaskSid": long?,
"ActivityType": EActivityType (see below),
"Dt": date?,
"IsUnread": bool,
"IsCompleted": bool,
"Nt": string
}
Enums:
EActivityType {
None = 0,
PhoneCall = 1,
EMail = 2,
Meeting = 3,
Note = 4,
Notification = 5,
Other = 10
}
HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.
HTTP RESPONSE:
{
"ActivityId": long,
"StaffSid": long?,
"ProjectSid": long?,
"TaskSid": long?,
"ActivityType": long,
"ActivityTypeName": string,
"EventType": long?,
"EventTypeName": string,
"Dt": date?,
"IsUnread": bool,
"IsCompleted": bool,
"Nt": string,
"Data": string,
"CreatedDt": date,
"CreatedBy": long,
"EMailId": string,
"EMailStatus": long?,
"EMailStatusName": string,
"NoticeMessage": {
"Body": string,
"LinkText": string,
"href": string,
"NoticeType": string,
"CategoryType": string,
"Subject": string,
"NoticeSettings": string,
},
"Staff_Nm": string,
"Project_Nm": string,
"Client_Sid": long,
"Client_Nm": string
}
This endpoint is used to remove Activities from a Project in the BigTime system.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE: /project/activity
HTTP REQUEST:
{
"id":0
}
HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.
HTTP RESPONSE:
{
"success": true
}
This section of the API is concerned with project labor codes.
This endpoint is used to fetch all Labor Codes from the BigTime system. There is an optional parameter to ShowInactive LaborCodes.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/LaborCodeTypes?showInactive={true/false/?}
HTTP STATUS: 200 Success.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.
HTTP RESPONSE:
[
{
"SID": long,
"AcctSysSID": long,
"AcctSysSID2": long,
"AcctSysSID_nm": string,
"Code": string,
"Desc": string,
"InUse": long,
"IsInactive": bool,
"IsLocked": bool,
"IsNoCharge": bool,
"IsTaxable": bool,
"Nm": string,
"Rate1": double,
"Rate2": double,
"Rate3": double,
"Rate4": double,
"Rate5": double,
"SortOrd": long
}, ...
]
This endpoint is used to fetch the Labor Codes attached to a project in BigTime. If there are no Labor Codes attached to the project, it will return all Labor Codes in the system.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/LaborCode?projectId={projectId}
HTTP STATUS: 200 Success.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.
HTTP RESPONSE:
[
{
"SID": long,
"AcctSysSID": long,
"AcctSysSID2": long,
"AcctSysSID_nm": string,
"Code": string,
"Desc": string,
"InUse": long,
"IsInactive": bool,
"IsLocked": bool,
"IsNoCharge": bool,
"IsTaxable": bool,
"Nm": string,
"Rate1": double,
"Rate2": double,
"Rate3": double,
"Rate4": double,
"Rate5": double,
"SortOrd": long
}, ...
]
This endpoint is used to attach LaborCodes to Projects in the BigTime system. It returns a list of all LaborCodes attached to that project after the update.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST: /project/laborCode
HTTP REQUEST:
{
"id": 0, //ProjectSid
"laborCodesToAdd" : [1, 2] //Array of LaborCodeSid
}
HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.
HTTP RESPONSE:
[
{
"SID": long,
"AcctSysSID": long,
"AcctSysSID2": long,
"AcctSysSID_nm": string,
"Code": string,
"Desc": string,
"InUse": long,
"IsInactive": bool,
"IsLocked": bool,
"IsNoCharge": bool,
"IsTaxable": bool,
"Nm": string,
"Rate1": double,
"Rate2": double,
"Rate3": double,
"Rate4": double,
"Rate5": double,
"SortOrd": long
}, ...
]
This endpoint is used to remove Activities from a Project in the BigTime system. It returns a list of all LaborCodes attached to that project after the update.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE: /project/activity
HTTP REQUEST:
{
"id": 0,
"laborCodesToRemove" : [1, 2]
}
HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.
HTTP RESPONSE:
[
{
"SID": long,
"AcctSysSID": long,
"AcctSysSID2": long,
"AcctSysSID_nm": string,
"Code": string,
"Desc": string,
"InUse": long,
"IsInactive": bool,
"IsLocked": bool,
"IsNoCharge": bool,
"IsTaxable": bool,
"Nm": string,
"Rate1": double,
"Rate2": double,
"Rate3": double,
"Rate4": double,
"Rate5": double,
"SortOrd": long
}, ...
]
By submitting a simple query to this api, you'll get a list of custom fields for a specific project.
You can use a GET request to pull the list of custom fields for a specific project. Note that a user cannot pull project custom field data for a project 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. No additional parameters are required/supported.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /project/customfields/{sid}
HTTP RESPONSE: (array of Project Custom Field objects -- see below for details)
You can use a POST request to pull a list of custom fields with a specific field name. If you decide to not specify a field name or pass an empty list, the below query will return a full list of custom fields for all your projects. Note that a user cannot pull project custom field data for a project 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. No additional parameters are required/supported.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST: /project/CustomFieldsByName
POST CONTENT:
[
"Custom Field Name 1",
"Custom Field Name 2",
..
]
HTTP RESPONSE: (array of Project Custom Field objects -- see below for details)
You can use a POST request to update an existing project's custom field list. To do this, POST to this URL with the project SID and a JSON array of Project Custom Fields objects. Your project's custom fields will be set according to the JSON array passed to this URL. 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: /project/customfields/{sid}
POST CONTENT:
{
"CustomFields":[
{
"ProjectSid":12345,
"Sid":6789,
"Value":"0"
},
{
"ProjectSid":12345,
"Sid":6790,
"Value":"1"
},
...
]
}
HTTP RESPONSE: (updated array of Project Custom Field objects -- see below for details)
You can also use this API to interact with project templates. Supported actions are described below.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET: /Project/Templates?{ShowInactive=true}
HTTP RESPONSE: array of Template objects
You can use a simple GET request to pull the details associated with a single entry. You should also note that a user cannot pull project 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: /project/template/{TemplateId}
HTTP RESPONSE: Template object
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 project template when you don't have that right).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post: /project/Template/{SystemId}
POST CONTENT: {TemplateDescription: "Example Template",
FName: "My Test Name"}
You can include ANY of the Update fields below,
but you MUST include the required (*) fields.
HTTP RESPONSE: updated Template object ("basic" view -- 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: /project/template/{TemplateId}
POST CONTENT: {ProjectSid: {ProjectSid},
FName: "My Test Name"}
** You can include ANY of the Update fields below.
However - you cannot "zero-out" or remove any of the
required (*) fields.
HTTP RESPONSE: updated Template object ("basic" view -- see below for details)
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE: /project/Template/{TemplateId}
HTTP RESPONSE: 200 is a successful delete.
For each of the operations listed above, you will post or "get" one or more project 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 AddUpdate and Update views. Required fields are flagged with an "*" character.
| Field | Type | Description | View(s) |
|---|---|---|---|
| SystemId | Integer | Unique SID code for this record. | Basic, Detailed, Update* |
| Nm | String | The name for this project (note that BigTime uses a project's "display name" instead of the name in most of the views you see in the system). | Basic, Detailed, Update* |
| DisplayName | String | Since some firms use project "name" and others use "code," BigTime supports a display name that makes it easier to identify a project out of context (eg - in a timesheet or a report). Often, the display name is a simple a "Client:Project", but it can include any combination of the project's name, code, client name, client code and "type." This value is set by a firm's administrator and used throughout the system. Typically, when a new project is created in the system, the display name is auto-filled. So, DisplayName is not a required field when a new project is created. | Basic, Detailed, Update |
| ProjectCode | String | A unique user-friendly project code associated with each project. | Basic, Detailed, Update* |
| TypeId | Integer | Unique SID code for the project's TYPE. | Basic, Detailed, Update |
| StartDt | Date | Start date for the project (defaults to today if a project is created without one, and field cannot be set to an empty value). | Basic, Detailed, Update |
| EndDt | Date | When a project is terminated, this date contains the date it is closed "as of" (important because new time entries will be blocked on closed projects on/after their termination date). | Basic, Detailed, Update |
| IsInactive | True/False | Inactive projects have this value set to TRUE. Note that you cannot update this value directly (instead, you would need to set StatusProd to an inactive status value to make a project inactive). | Basic, Detailed |
| StatusProd | Integer | The production status code controls the specific reason behind a project's deactivation (eg - on-hold, cancelled, closed). The available values for this list are controlled by the administrator in BigTime's settings section. | Detailed, Update |
| StatusProd_nt | String | Unique SID code for this record. | Detailed, Update |
| StatusBill | Integer | The billing status code determines whether or not a project shows up on the "draft invoicing" screens and reports. Note that house accounts (eg - internal projects that are used to track time but are not billed out) are typically setup with an inactive billing status. In addition, keep in mind that projects may be "closed" to time tracking BEFORE they are "closed" in the billing system. | Detailed, Update |
| Notes | String | A text field used to house a project's outline/description. | Basic, Detailed, Update |
| IsAllStaff | True/False | TRUE if a project can be viewed/billed against by every member of the staff (no matter who is actually staffed on the project's team list). This value is frequently set to TRUE for internal projects. | Detailed, Update |
| IsNoCharge | True/False | TRUE if a project is an internal (non-billing) project. All time/expense charges on projects marked as IsNoCharge are flagged as non-billable automatically when a user submits them. | Detailed, Update |
| InvoiceType | Integer | Unique SID code for the type of invoice that this project uses (eg - T&M, retainer). These values are activated/controlled by the system administrator in the BigTime settings area. | Detailed, Update |
| InvoiceTotals | Integer | Unique SID code for the default invoice "sub-total" for this project (0=none; 1=staff; 2=labor code; 3=task; 4=team role; 5=title) These values are set automatically each time an invoice is created and retained for use on subsequent invoices. | Detailed, Update |
| ContractNotes | String | If there are special invoicing instructions on the project, then those instructions are contained in this free-form text field. | Detailed, Update |
| InvoiceNotes | String | If the project's invoices get a special note by default (when they are created), then that free-form text note is contained here. | Detailed, Update |
| BillingRate BaseRateStyle |
ENUM String |
Projects all have a base billing rate, and this enum determines where that rate is pulled from. Acceptable values are StaffRate1, StaffRate2, StaffRate3, StaffRate4, StaffRate5, ActivityRate1, ActivityRate2, ActivityRate3, ActivityRate4, ActivityRate5. The BaseRateStyle is a string representation of that base rate (useful for display). |
Detailed, Update |
| BasicRate | Numeric | If a project uses a simple flat rate of $X/hour, then that rate can be set using this field. | Detailed, Update |
| QBClassDefault | Integer | If the user is attached to QuickBooks and is setup to post class information with their time, expenses and/or invoices, then this value may contain a "default" class for any items attached to this project. | Detailed, Update |
| QBCustomerId QBCustomerId_nm |
String | If the user is attached to QuickBooks and this project is linked to a QuickBooks customer/job -- then this value is the external QuickBooks id for that customer/job. Note that we also return a read-only copy of the external customer NAME for convenience/display (QBCustomerId_nm is not updatable). | Detailed, Update |
| ClientId | Integer | Unique SID code for the client/customer record to which this project is attached. | Basic, Detailed, Update |
| PrimaryContactId | Integer | Unique SID code for the primary "contact" record to which this project is attached (see the ContactList below). | Basic, Detailed, Update |
| BillingContactId | Integer | Unique SID code for the "contact" record to which invoices are sent for this specific project (see the ContactList below). | Basic, Detailed, Update |
| ContactList | Contacts* | Each project in the system can be attached to multiple "contact" records, and this collection is used to dispaly a listing of those records for each project. Note that projects aren't REQUIRED to have contact data (so any given project may have NO ContactList). There is not a limit to the number of contacts that can be added to each project, but there can be one and only one contact tagged as "Primary" and one and only one contact tagged as "Billing." | Detailed |
| AddressList | Addresses* | Each project in the system can be attached to multiple "address" records as well, and this collection displays a listing of those records for each project. Just like contact records, projects aren't REQUIRED to have address data (so any given project may have NO AddressList). There is no limit to the number of address records that can be added to each project (projects attached to multiple systems -- like QuickBooks, Basecamp, Highrise -- frequently have different addresses for each of those systems). However, there can be one and only one address tagged as "Primary", "Billing" and "Client." | Detailed |
| Client | Client* | Each project in the system can be attached to a single "client" record, and this object is used to dispaly the data associated with this project's client. Note - to move a project to another client, you will need to set the ClientId value. | Detailed |
| DtCreated | Date | UTC Date that the project was created in the system. | Basic, Detailed |
| DtModified | Date | UTC Date that the project was last modified by anyone (including external systems like QuickBooks or Xero). | Basic, Detailed, Update |
| CostCenterA CostCenterB CostCenterC |
Integer | Each project/staffer in the system can be assigned up to 3 cost center values (eg - office, partner, department). Those cost centers are useful for reporting -- and they are set by the administrator in the settings area. Note that you can see the list of available cost center values for this field by pulling data from the PICKLIST area (picklist/fieldValues/CCenter1 - CCenter3). | Detailed, Update |
| UdfList | Udfs** | A list of custom fields defined for the project. | Detailed |
Project Templates use the same fields as a project. Below are any additional fields that Project Templates use that are not part of the standard project object fields
| Field | Type | Description | View(s) |
|---|---|---|---|
| TemplateDescription | String | A description of the project template | Basic, Update |
| Field | Type | Description | View(s) |
|---|---|---|---|
| Id | 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, Update* |
| FullNm | String | The contact's full name (first+last) -- useful for display. | Basic |
| Tag | String | PRIMARY, BILLING or OTHER -- this tag indicates the role a contact plays on a specific project. Note that a contact must be pulled with a specific projectSid in order to make the TAG a meaningful value. | Basic, Update |
| ProjectSid | Integer | The unique Id attached to this contact's project record. | Basic, Update* |
| ClientSid | Integer | The unique Id attached to this contact's client record. Note that you can set a ClientSid for a new contact, but you cannot update that value for an existing contact. | Basic, Update |
| FName | String | First (given) name. | Basic, Update |
| SName | String | Last (family) name. | Basic, Update |
| MName | String | Middle name | Basic, Update |
| Prefix | String | Mr/Mrs/Dr | Basic, Update |
| Title | String | Business title/position | Basic, Update |
| CompanyNm | String | Company Name | Basic, Update |
| String | Primary email address | Basic, Update | |
| Phone | String | Primary phone number | Basic, Update |
| Phone_2 | String | Secondary phone number | Basic, Update |
| Phone_3 | String | Mobile phone number (if one exists) | Basic, Update |
| Fax | String | Basic, Update | |
| Notes | String | Free form notes field | Basic, Update |
| ContactType | Long | See the picklist controller for acceptable values in this field (picklist/fieldValues/LookupContactType). | Basic, Update |
| Address | Address** | The address object attached to this contact (see details below). | Basic, Update |
| LinkedProjects | LinkedProjectRecord** | The LinkedProjectRecords attached to this contact (see details below). | Basic |
| Field | Type | Description | View(s) |
|---|---|---|---|
| Id | Integer | Unique SID code for this record. Note that this value is an attribute on the main Address object if you are downloading xml. | Basic, Detailed |
| Address | String | Street address (can be multi-line) | Basic, Detailed |
| City | String | Basic, Detailed | |
| State | String | State, Province or county (depending on the address' country of origin) | Basic, Detailed |
| Zip | String | Postal code | Basic, Detailed |
| Country | String | Country of origin. | Basic, Detailed |
| FullAddress | String | Useful for display: the full address (with line breaks and including the address, csz and country). | Basic,Detailed |
| Field | Type | Description | View(s) |
|---|---|---|---|
| SystemId | Long | Unique SID code for this project. Note that this value is the SID of the project linked to this contact. | Basic |
| Nm | String | The name for this project (See Project Object: Field Details) | Basic |
| DisplayName | String | The display name for this project (See Project Object: Field Details) | Basic |
| ProjectCode | String | The project code associated with each project (See Project Object: Field Details) | Basic |
| IsInactive | Boolean | Project active status (See Project Object: Field Details) | Basic |
| PrimaryContactId | Long | The unique SID of the primary contact object on this project (See Contact Object Field Id) | Basic |
| BillingContactId | Long | Useful for display: the full address (with line breaks and including the address, csz and country). | Basic |
While the information pulled from BigTime will come as an object as outlined above, we've added several update-specific fields to make changes to contact data more streamlined. Each of the fields listed below is supported by the Add/Update features in the API. They are each properties of the main ProjectDetail object.
| Field | Type | Description | View(s) |
|---|---|---|---|
| PContactFName | String | Used to update the first name of the primary contact. | Update |
| Field | Type | Description | View(s) |
|---|---|---|---|
| StaffSid | Integer | Unique SID for this Staffer. | Basic, Update* |
| ContactRole | Integer | Unique SID for this Project Team Member's Project role. This SID can be used to lookup the Project role name using the /picklist/FieldValues/LookupProjectTeamRoles endpoint. Please see the Picklists section of the API documentation for more details. | Basic, Update |
| TeamLead | True/False | Project Team Members that are set to be team lead a project have this set to be TRUE. | Basic, Update |
| FName | String | First (given) name. | Basic |
| SName | String | Last (family) name. | Basic |
| String | Primary email address | Basic | |
| StaffNm | String | The Project Team Member's full name (first+last). | Basic |
| PrimaryPhone | String | Main phone number for the staffer | Basic |
| Field | Type | Description | View(s) |
|---|---|---|---|
| ProjectSid | Integer | Unique SID for this Project the Staff Team is assigned to. | Basic, Update* |
| TeamID | Integer | Unique SID for this Staff Team. A list of available SIDs can be looked up using the /picklist/FieldValues/StaffTeamList endpoint. Please see the Picklists section of the API documentation for more details. | Basic, Update* |
| TeamNm | String | Staff Team name. | Basic |
| TeamDesc | String | Staff Team description. | Basic |
| TeamSort | Integer | Value used to sort teams (desc). | Basic |
| Selected | True/False | If the Staff Team is in use by the project. | Basic |
| Field | Type | Description | View(s) |
|---|---|---|---|
| ProjectSid | Integer | Unique SID for this Project. | Basic, Update* |
| Sid | Integer | Unique SID for the Custom Field. | Basic, Update* |
| Name | String | Name of the Custom Field. | Basic |
| Value | String | Value of the Custom Field. | Basic, Update* |
You can also use this API to interact with a project's custom bill rates. Supported actions are described below.
You can use a simple GET request to pull custom rate details associated with a project.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /project/rates/{ProjectSID} HTTP RESPONSE: (array of ProjectRateobjects -- see below for details)
You can use a simple GET request to pull the details associated with a single custom bill rate.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /project/rate/{CustomRateSID} HTTP RESPONSE: (Single ProjectRateobject -- 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 project when you don't have that right).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post: /project/rate
POST CONTENT: {"ProjectSid": 0, "StaffSid":0, "CatSid":0, "TaskSid":0, "RateVal": 0}
You can include ANY of the Update fields below,
but you MUST include the required (*) fields.
HTTP RESPONSE: (new ProjectRate 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: /project/rate/{CustomRateSID} - customratesid is from the GET operation above, i.e. /project/rates/{ProjectSID}
POST CONTENT: {"ProjectSid": 0, "StaffSid":0, "CatSid":0, "TaskSid":0, "RateVal": 0}
** You can include ANY of the Update fields below.
However - you cannot "zero-out" or remove any of the
required (*) fields.
HTTP RESPONSE: (updated ProjectRate object -- see below for details)
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE: /project/rate/{CustomRateSID} - customratesid is from the GET operation above, i.e. /project/rates/{ProjectSID}
HTTP RESPONSE: 200 is a successful delete.
| Field | Type | Description | View(s) |
|---|---|---|---|
| SID | Integer | Unique SID code for this rate record. | |
| ProjectSid | Integer | The unique Id attached to this rate's project record. | Update* |
| StaffSid | Integer | Unique SID for this Staffer.See the picklist controller for acceptable values in this field (picklist/staff) | Update* |
| CatSid | Integer | Unique SID code for the Labor Code.See the picklist controller for acceptable values in this field (picklist/laborcodes). | Update* |
| TaskSid | Integer | Unique SID code for the task. See the task controller for acceptable values in this field (/task/listByProject/{ProjectSid}?{showCompleted=True/False}) | Update* |
| RateVal | Integer | Rate value for this custom bill rate | Update* |