BigTime's staff api provides access to the list of users in the system.

Getting a listing of Staff

try it

• Click the GET button below to view the information returned by this url.

• Get

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff?{ShowInactive=true}
HTTP RESPONSE:  (array of Staff objects ("basic" view -- see below for details)

Pulling the detail for a specific staffer.

try it

• BasicDetailed
• 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 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:  /staff/detail/{systemid}?&View={Detailed/Basic}
HTTP RESPONSE:  (Staff object -- see below for details)

Creating a NEW staffer.

try it

• {"SName": "Test Staff Name", "EMail": "TestStaffEmail@email.com"}
• 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 staffer when you don't have that right).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/add/?inviteUser={true/false}
HTTP RESPONSE:  (Staff object -- see below for details)

Invite Existing Staff to BigTime

try it

• {"InviteStaffSids":[1000, 2000]}
• Post

This endpoint can be used to invite existing staff to BigTime.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /staff/invite
POST CONTENT:
{  
   "InviteStaffSids":[  
		1000,
		1001,
		1002,
		...,
		n
   ]
}

HTTP STATUS: 200 Success.
HTTP STATUS: 202 Completed with errors.
HTTP RESPONSE: 
{
    "SuccessfullyInvitedStaffSids": [
		1001,
		...,
		n,
    ],
    "FailedInviteStaffErrors": {
        "StaffSids": [
			1000,
			1002
		],
        "FailureErrorMessages": [
            {
                "StaffSid": 1000,
                "ErrorMessage": "The system failed to invite the staff."
            },
            {
                "StaffSid": 1002,
                "ErrorMessage": "The system failed to invite the staff."
            },
		]
    }
}

Retrieve Staff Allocation Details

try it

• Get

This endpoint can be used to fetch staff allocations by week or month for a specified date range. Failing to submit a valid value for any of the fields listed in the request object will raise an error. In order to use this endpoint you will need permissions to view task budget data. You will only recieve a response containing staffer data your have permission to view.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/staffAllocations/?startDate={Date}&endDate={Date}&allocationPeriodType={weekly/monthly}
HTTP RESPONSE:  (StaffAllocationSummaryDetail object -- see below for fields)

StaffSkills

This section of the API is concerned with managing skills and staff skill assignmnets.

GET /Staff/SkillTypes

try it

• Get

This endpoint is used to fetch the Skill Types present in BigTime. These values are then used in Skill creation.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/skillTypes

Response Format

HTTP STATUS: 200 Success.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.

HTTP RESPONSE: 
{
    "1": "Skill",
    "2": "Certification",
    "3": "Language",
    "4": "Other"
}

GET /Staff/Skill

try it

• Get

This endpoint is used to fetch existing Skills from the BigTime system.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/skill

Response Format

HTTP STATUS: 200 Success.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.

HTTP RESPONSE: 
[
    {
        "SkillSID": long,
        "SkillNm": string,
        "SkillDesc": string,
        "SkillTypeSID": long,
        "SkillCategorySID": long,
        "SkillCategoryNm": string,
        "RoleList": long[],
        "IsExpiring": bool,
        "IsRating": bool,
        "CreatedDt": date,
        "ModifiedDt": date
    },
	...
]

POST /Staff/Skill

try it

• { "SkillNm": "SkillNm", "SkillDesc": "SkillDesc", "SkillTypeSID": 1, "SkillCategorySID":0, "SkillCategoryNm":"SkillCategoryNm", "RoleList": [], "IsExpiring": true, "IsRating": true }
• Post

This endpoint is used to create Skills in the BigTime system.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /staff/skill
HTTP REQUEST: 
{
    "SkillNm": string,
    "SkillDesc": string,
    "SkillTypeSID": long,
    "SkillCategorySID": long,
    "SkillCategoryNm":string
    "RoleList": long[],
    "IsExpiring": bool
    "IsRating": bool
}

Response Format

HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.

HTTP RESPONSE: 
{
	"SkillSID": long,
    "SkillNm": string,
    "SkillDesc": string,
    "SkillTypeSID": long,
    "SkillCategorySID": long,
    "SkillCategoryNm":string
    "RoleList": long[],
    "IsExpiring": bool,
    "IsRating": bool,
	"CreatedDt": date,
	"ModifiedDt": date,
}

DELETE /Staff/Skill

try it

• { "id":0 }
• Post

This endpoint is used to remove Skills from the BigTime system.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /staff/skill
HTTP REQUEST: 
{
	"id":0
}

Response Format

HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.

HTTP RESPONSE: 
{
    "success": true
}

GET /Staff/SkillAssignment

try it

• Get

This endpoint is used to fetch existing skills currently assigned to a designated Staffer.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/SkillAssignment/{staffId}

Response Format

HTTP STATUS: 200 Success.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.

HTTP RESPONSE: 
[
    {
        "StaffSkillSID": long,
        "StaffSID": long,
        "FName": string,
        "SName": string,
        "FullName": string,
        "SkillSID": long,
        "SkillNm": string,
        "SkillDesc": string,
        "IndustrySID": long,
        "IndustryNm": string,
        "SkillCategoryNm": string,
        "SkillTypeSID": long,
        "SkillTypeNm": string,
        "IsExpiring": bool,
        "IsRating": bool,
        "Rating": decimal,
        "CreatedDt": date,
        "CreatedBy": string,
        "ModifiedDt": date,
        "ModifiedBy": string,
        "StaffSkillCertificationSID": long,
        "FileType": long,
        "IsExpired": bool,
        "CertificationAssetName": string,
        "CertificationCreatedBy": string,
        "CertificationModifiedBy": string
    },
	...
]

POST /Staff/SkillAssignment

try it

• { "StaffSid":0, "SkillSid":0, "IndustrySID":0, "Rating":0, "IsActive":true }
• Post

This endpoint is used to assign Skills to Staffers in the BigTime system.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /staff/SkillAssignment
HTTP REQUEST: 
{
    "StaffSid": long,
    "SkillSid": long,
    "IndustrySID": long,
    "Rating": decimal,
    "IsActive": bool
}

Response Format

HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.

HTTP RESPONSE: 
{
    "StaffSkillSID": long,
    "StaffSID": long,
    "SkillSID": long,
    "IndustrySID": long,
    "Rating": decimal,
    "CreatedDt": date,
    "ModifiedDt": date,
    "IsActive": bool
}

DELETE /Staff/SkillAssignment

try it

• { "id":0 }
• Post

This endpoint is used to remove Skills assignments from Staffers in the BigTime system.

Request Format

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /staff/SkillAssignment
HTTP REQUEST: 
{
	"id":0
}

Response Format

HTTP STATUS: 200 Success.
HTTP STATUS: 4xx User Error.
HTTP STATUS: 403 Forbidden.
HTTP STATUS: 5xx Error.

HTTP RESPONSE: 
{
    "success": true
}

Staffer Custom Fields

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

Getting a list of staffer custom fields.

try it

• Get

You can use a GET request to pull the list of custom fields for a specific staffer. Note that a user cannot pull staffer custom field data for a staffer 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:  /staff/UDFList/{sid}
HTTP RESPONSE:  (array of Staffer Custom Field objects -- see below for details)

Getting a list of staffer custom fields by field name.

try it

• Submit

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 staffers. Note that a user cannot pull staffer custom field data for a staffer 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:  /staff/UDFListByName
POST CONTENT:
[
	"Custom Field Name 1",
	"Custom Field Name 2",
	..
]
HTTP RESPONSE:  (array of Staffer Custom Field objects -- see below for details)

Updating existing custom fields on a staffer.

try it

• Submit

You can use a POST request to update an existing staffer's custom field list. To do this, POST to this URL with the staffer SID and a JSON array of Staffer Custom Fields objects. Your staffer'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:  /staff/UDFList/{sid}
POST CONTENT:
{  
   "UDFList":[  
      {  
         "Sid":6789,
         "Value":"0"
      },
      {  
         "Sid":6790,
         "Value":"1"
      }, 
	  ...
   ]
}
HTTP RESPONSE:  (updated array of Staffer Custom Field objects -- see below for details)

Staff: Field Details

For each of the operations listed above, you will post or "get" one or more staff 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, and fields marked with a "!" character require the ViewPersonalData permit type to view and update.

Additional fields if integrated with QuickBooks

Additional fields if integrated with Sage Intacct

Address Object Field Details

Staffer Custom Field Object Details

StaffAllocationSummaryDetail Object Details

StaffAllocationDetail Object Details