;
api login

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.

Getting a listing of "My Projects."
try it
  • Click the GET button below to view the information returned by this url.

  • Get

By submitting a simple query to this api, you'll get a listing of project data (we return the "simple" view on the listings page). No additional parameters are required/supported.
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)

Pulling the detail for a specific project.
try it
  • Get

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)

Creating a NEW project.
try it
  • Post

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)

Updating Existing Projects.

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)

Deleting a Project.

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.

Project Contacts

You can also use this API to interact with a project's contacts. Supported actions are described below.

Getting a listing of a project's contacts.

By submitting a simple query to this api, you'll get a listing of contact data (we return the "basic" view on the listings page). No additional parameters are required/supported.
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)

Pulling the detail for a specific contact.

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)

Creating a NEW contact.
try it
  • Post

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)

Updating existing contacts.
try it
  • Submit

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)

Deleting a contact.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /project/Contact/{SystemId}?ProjectSid={ProjectSID}
HTTP RESPONSE:  200 is a successful delete.

Project Team

You can also use this API to interact with a project's team. Supported actions are described below.

Getting a list of project team members.

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)

Updating an existing project's team members.

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.

Project Staff Teams

You can also use this API to interact with a project's staff teams. Supported actions are described below.

Getting a list of project staff teams.

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)

Updating an existing project's staff teams.

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.

Project Custom Fields

By submitting a simple query to this api, you'll get a list of custom fields for a specific project.

Getting a list of project custom fields.

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)

Getting a list of project custom fields by field name.

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)

Updating existing custom fields on a project.

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)

Project Object: Field Details

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.

FieldTypeDescriptionView(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 QB 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 Object: Contact Object Field Details

FieldTypeDescriptionView(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
EMail 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
Contact Object: Address Object Field Details

FieldTypeDescriptionView(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
Contact Object: Linked Project Record Field Details

FieldTypeDescriptionView(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

Updating Project Contact Information

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.

FieldTypeDescriptionView(s)
PContactFName String Used to update the first name of the primary contact. Update
Project Team Member Object Field Details

FieldTypeDescriptionView(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
EMail 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
Project Staff Team Object Field Details

FieldTypeDescriptionView(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
Project Custom Field Object Details

FieldTypeDescriptionView(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*