REST API Reference

Welcome to NiceJob's v2 REST API. Our API accepts JSON-encoded and form-encoded request bodies, returns JSON-encoded responses, uses OAuth2 for authentication, and uses standard HTTP response codes.

The API and this documentation are still very much a work in progress. Please refer to the API CHANGELOG for the latest changes.

The API is currently in alpha, meaning that endpoints, request formats, and response formats remain subject to change. We will notify all API users when breaking changes are going to be made.

Authentication

For authentication, we use OAuth2: a 3-step procedure comprising a user redirect for the obtainment of consent, and two subsequent client-to-NiceJob POST requests. Much has been written about OAuth2. If you are unfamiliar with it, we recommend these resources:

Use the following endpoints for your OAuth2 requests to NiceJob:

Authorization endpointhttps://api.nicejob.com/oauth/authorize
Token endpointhttps://api.nicejob.com/oauth/token
Revocation endpointhttps://api.nicejob.com/oauth/revoke
Introspection endpointhttps://api.nicejob.com/oauth/introspect

The 3 steps to obtain an access token are thus:

REDIRECThttps://api.nicejob.com/oauth/authorize
▾
Response:
▾
Get authorization code

Gain the user's consent by redirecting them to the authorization endpoint. We then redirect the user back to your redirect_uri, with the authorization code attached as a query parameter.

POSThttps://api.nicejob.com/oauth/token
▾
Response:
▾
Get refresh token

Send that authorization code to the token endpoint to obtain a refresh token. Use grant_type: "authorization_code".

POSThttps://api.nicejob.com/oauth/token
▾
Response:
▾
Get access token

Send the refresh token received above to the token endpoint to obtain an access token. Use grant_type: "refresh_token".

With the access token obtained, you are free to query the API. See the requests section of the API for information on how to format your requests.

Access token expiry & refresh

Access tokens are valid for a period of 24 hours. You are free to refresh them at any point beforehand. To refresh an access token, repeat the get access token step above.

Refresh token expiry

Refresh tokens do not expire.

Refresh token revocation

In the case that you or the user would like to end the connection between applications, refresh tokens may (and should) be revoked.

To revoke a refresh token, make a POST request to the revocation endpoint using the format defined in the OAuth2 standard.

Alpha warning: Token revocation is not yet available.

Token introspection

Alpha warning: Token introspection is not yet available.

Authentication for webhooks

Note that webhook authentication – given that it is developer-scoped via a client_credentials grant type and not company-scoped – follows a different authentication protocol. See the Webhook authentication section below for more.

Scopes

Your app's credentials – and all access tokens derived from them – are restricted to work within an array of provided scopes. You can view your app's permitted scopes by signing in and checking your app's credentials. The scope(s) required to access each endpoint are provided in the endpoint documentation below.

Requests

The NiceJob API expects incoming requests to be in JSON format, with a Content-Type: application/json header.

Responses & Errors

Status codes

We return 200 status codes for all properly processed requests. Requests with malformed input data will return a 400, while unauthorized requests – including those with an expired access token – will return a 401. Server errors from our side will return a ≥500.

Errors

There are cases however where successfully formatted and authenticated requests do not produce their intended action – e.g. a creation request with a duplicated unique key. Such cases will return a 200 status code but output an error message in the response's error field.

Response format

Any successful API request (status 200) will receive, in response, a JSON object with the following fields:

  • cursor
    string | null
    Applies to list requests only. When more results are available, a pagination cursor will be returned. Otherwise will be null. Use cursors to return the next page of results.
  • data
    object | null
    The request data, corresponding to the Response data descriptions accompanying each request in the documentation below.
  • error
    string | null
    The aforementioned error message.

Changelog

See the API Changelog for the latest changes to this API.

During the API's alpha stage, we will be providing the time of last update in the documentation sidebar.

Booking

A Booking represents a job that a user Company has arranged with one of their customers (known as a Person herein). The Booking entity can be created at the time of scheduling. Upon completion, the Booking is to be updated as complete. Booking completion will normally trigger a CampaignEnrollment, depending on the Company's Campaign settings.

If your software supports job grouping, you may want to consider creating one Booking with subordinate Visits. See the Visit entity description for more information.

The Booking entity

Properties

  • id
    stringUnique
    The Booking entity ID.
  • amount
    float | null
    The payment amount associated with the Booking, in dollars.
  • complete
    boolean
    Whether the work associated with the Booking has been completed.
  • completed_time
    Date | null
    The date the Booking was completed. The value should be a Date when complete: true
  • created_at
    Date
    Entity creation date.
  • employee_ids
    Array<string>
    Employees who worked on the Booking.
  • name
    string | null
    A name for the Booking.
  • person_ids
    Array<string>
    The clients' Person entity IDs.
  • scheduled_time
    Date | null
    The date the Booking is/was scheduled for.
  • tags
    Array<string>
    Custom tags associated with the Booking. The noreview tag will prevent a Booking from triggering a CampaignEnrollment on completion.
  • updated_at
    Date
    Entity last-updated date.

List Bookings

Retrieve a paginated list of Booking entities.

GEThttps://api.nicejob.com/v2/bookings?person_id=$PERSON_ID&cursor=$CURSOR
▾
Response:
▾

Optional query parameters

  • cursor
    string?
    A pagination cursor.
  • person_id
    string?
    Filter results by Person.

Response data

Returns an array of Booking entities, up to 20 items long.

Scopes required

bookings

Get a Booking

Retrieve an individual Booking entity.

GEThttps://api.nicejob.com/v2/bookings/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Booking entity if found. Returns a null result otherwise.

Scopes required

bookings

Create a Booking

POSThttps://api.nicejob.com/v2/bookings
▾
Response:
▾

Request body

  • amount
    float?
    The payment amount associated with the Booking, in dollars.
  • complete
    boolean?
    Whether the work associated with the Booking has been completed.
  • completed_time
    Date?
    The date the Booking was completed. The value should be a Date when complete: true
  • created_at
    Date
    Entity creation date.
  • employee_ids
    Array<string>
    Employees who worked on the Booking.
  • items
    Array<object>
  • items[].amount
    object
  • items[].amount.currency_code
    string?
  • items[].amount.value
    int
  • items[].catalog_product_id
    string
  • items[].description
    string?
  • items[].external_source_id
    string
  • items[].name
    string
  • items[].quantity
    int
  • name
    string?
    A name for the Booking.
  • person_id
    string?Deprecated
    The client's Person entity ID.
  • person_ids
    Array<string>
    The clients' Person entity IDs.
  • scheduled_time
    Date?
    The date the Booking is/was scheduled for.
  • tags
    Array<string>
    Custom tags associated with the Booking. The noreview tag will prevent a Booking from triggering a CampaignEnrollment on completion.

Response data

Returns the new Booking entity.

Scopes required

bookings

Update a Booking

Updates a Booking entity. The values you provide will overwrite any previously-existing values on the entity.

POSThttps://api.nicejob.com/v2/bookings/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    The Booking entity ID.

Request body

  • amount
    float?
    The payment amount associated with the Booking, in dollars.
  • complete
    boolean?
    Whether the work associated with the Booking has been completed.
  • completed_time
    Date?
    The date the Booking was completed. The value should be a Date when complete: true
  • created_at
    Date
    Entity creation date.
  • employee_ids
    Array<string>
    Employees who worked on the Booking.
  • items
    Array<object>
  • items[].amount
    object
  • items[].amount.currency_code
    string?
  • items[].amount.value
    int
  • items[].catalog_product_id
    string
  • items[].description
    string?
  • items[].external_source_id
    string
  • items[].name
    string
  • items[].quantity
    int
  • name
    string?
    A name for the Booking.
  • person_id
    string?Deprecated
    The client's Person entity ID.
  • person_ids
    Array<string>
    The clients' Person entity IDs.
  • scheduled_time
    Date?
    The date the Booking is/was scheduled for.
  • tags
    Array<string>
    Custom tags associated with the Booking. The noreview tag will prevent a Booking from triggering a CampaignEnrollment on completion.

Response data

Returns the updated Booking entity, if found. Returns a null result otherwise.

Scopes required

bookings

Case

A Case represents a legal case that a user Company has arranged with one of their customers (known as a Person herein). Upon completion, the Case is to be updated as complete. Case completion will normally trigger a CampaignEnrollment, depending on the Company's Campaign settings.

The Case entity

Properties

  • id
    stringUnique
    The Case entity ID.
  • completed_time
    Date | null
    The date the Case was completed.
  • created_at
    Date
    Entity creation date.
  • description
    string | null
    A description of the Case.
  • employee_ids
    Array<string>
    Employees associated with the Case.
  • name
    string | null
    A name for the Case.
  • person_id
    string
    The client's Person entity ID.
  • status
    Enum<"pending" | "open" | "closed"> | null
  • tags
    Array<string>
    Custom tags associated with the Case.
  • updated_at
    Date
    Entity last-updated date.

List Cases

Retrieve a paginated list of Case entities.

GEThttps://api.nicejob.com/v2/cases?person_id=$PERSON_ID&cursor=$CURSOR
▾
Response:
▾

Optional query parameters

  • cursor
    string?
    A pagination cursor.
  • person_id
    string?

Response data

Returns an array of Case entities, up to 20 items long.

Scopes required

cases

Get a Case

Retrieve an individual Case entity.

GEThttps://api.nicejob.com/v2/cases/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Case entity if found. Returns a null result otherwise.

Scopes required

cases

Create a Case

POSThttps://api.nicejob.com/v2/cases
▾
Response:
▾

Request body

  • completed_time
    Date?
  • created_at
    Date
    Entity creation date.
  • description
    string?
  • employee_ids
    Array<string>
  • name
    string?
  • person_id
    string?
  • status
    Enum<"pending" | "open" | "closed">?
  • tags
    Array<string>

Response data

Returns the new Case entity.

Scopes required

cases

Update a Case

Updates a Case entity. The values you provide will overwrite any previously-existing values on the entity.

POSThttps://api.nicejob.com/v2/cases/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Request body

  • completed_time
    Date?
  • created_at
    Date
    Entity creation date.
  • description
    string?
  • employee_ids
    Array<string>
  • name
    string?
  • person_id
    string?
  • status
    Enum<"pending" | "open" | "closed">?
  • tags
    Array<string>

Response data

Returns the updated Case entity, if found. Returns a null result otherwise.

Scopes required

cases

Campaign

Campaigns are the heart of NiceJob: they're the primary vehicle through which we provide value for our users. Campaigns consist of a sequence of messages between Company and Person (client), through which the company makes a request of the client.

NiceJob provides a series of campaigns, though the only one currently accessible through the API is the Get Reviews campaign.

For a Person to start receiving campaign messages, they must be enrolled.

The Campaign entity

Properties

  • id
    stringUnique
    The Campaign entity ID.
  • created_at
    Date
    Entity creation date.
  • description
    string | null
    A description of the campaign.
  • name
    string
    The campaign name.
  • objective
    Enum<"REVIEWS" | "RECOMMENDATIONS" | "EMPLOYEE_REVIEWS" | "ENGAGEMENT" | "BOOKINGS" | "WELCOME_NEW_CUSTOMERS" | "REWARD_LOYAL_CUSTOMERS" | "REPEAT_BUSINESS" | "REFERRALS"> | null
    The Campaign objective.
  • subject_kind
    Enum<"Person" | "Story" | "Employee" | "User">
  • updated_at
    Date
    Entity last-updated date.

List Campaigns

Retrieve a list of Campaign entities.

GEThttps://api.nicejob.com/v2/campaigns
▾
Response:
▾

Response data

Returns an array of Campaign entities.

Scopes required

campaigns

CampaignEnrollment

Campaign enrollments can be created in one of two ways: indirectly or directly. Indirect enrollment

Indirect enrollment occurs in response to Booking completion (wherein the Booking created with complete: true, or the complete field is updated to true), and is subject to the user's NiceJob settings. This is the recommended mode of enrollment: create the Booking entity, and let NiceJob take care of the rest. Direct enrollment

In some cases however, we permit direct enrollment of a Person into a campaign via the API. This is conveyed through the enrollments scope. Enrollment is conditional

Campaigns have rules that prevent multiple enrollments of the same Person. Therefore direct enrollment requests may not result in the creation of a CampaignEnrollment entity. Such requests will still return a 200 status code, but will have a null data field and an error message in the error field.

Direct enrollments will also fail where insufficient Person information is provided. Either an email address or a phone number is requred.

The CampaignEnrollment entity

Properties

  • id
    stringUnique
    The CampaignEnrollment entity ID.
  • campaign_id
    string
    The enrollment's parent Campaign entity ID.
  • created_at
    Date
    Entity creation date.
  • employee_ids
    Array<string>
  • tags
    Array<string>
  • updated_at
    Date
    Entity last-updated date.

Enroll a Person in a Campaign

Attempts to enroll a Person into a given campaign, defaulting to the Company's Get Reviews campaign.

Alpha warning: Currently, the Person entity must be created prior to the enrollment request. Soon we will enable an upsert + enroll functionality in this endpoint.
POSThttps://api.nicejob.com/v2/campaign_enrollments
▾
Response:
▾

Request body

  • campaign_id
    string?
    The enrollment's parent Campaign entity ID.
  • person_id
    string
    The subject Person entity ID.

Response data

Returns the new CampaignEnrollment entity, if successfully created.

Scopes required

enrollments

Company

The Company is the foundational entity in NiceJob. All other entity types fall within the company namespace. Access tokens are not tied to the authenticating user's user data but rather to the data of one of their companies.

The Company entity

Properties

  • id
    stringUnique
    Entity ID
  • address
    object | null
    The Company's validated address object.
  • address.address
    string | null
  • address.city
    string | null
  • address.country
    string | null
  • address.state
    string | null
  • address.unit
    string | null
  • address.zip
    string | null
  • company_name
    string
    The name of the company.
  • created_at
    Date
    Entity creation date.
  • email
    string | null
    The Company's validated email address.
  • language_preference
    string | null
  • migrated_from
    Enum<"paystone_hub"> | null
  • owner_first_name_override
    string | null
  • owner_last_name_override
    string | null
  • phone
    string | null
    The Company's validated phone number.
  • platform
    string | null
  • slug
    string | null
    A URL-safe company name slug.
  • updated_at
    Date
    Entity last-updated date.
  • website
    string | null
    The Company's homepage.

Get the Company

Retrieve the access token-bound Company entity.

GEThttps://api.nicejob.com/v2/company
▾
Response:
▾

Response data

Returns the Company entity to which the access token is bound.

Scopes required

company

Employee

An Employee represents an employee of the Company. Given that the Company manages the NiceJob account, the employee may also be a NiceJob User. Employees are often attached to Bookings.

Employee is referred to as Team member in app.

The Employee entity

Properties

  • id
    stringUnique
    The Employee entity ID.
  • archived_at
    Date | null
  • created_at
    Date
    Entity creation date.
  • email
    stringUnique
    The Employee's validated email address.
  • first_name
    string
  • last_name
    string | null
  • phone
    string | null
    The Employee's validated phone number.
  • position
    string | null
    The Employee's position at the Company.
  • updated_at
    Date
    Entity last-updated date.

List Employees

Retrieve a paginated list of Employee entities.

GEThttps://api.nicejob.com/v2/employees?email=$EMAIL&cursor=$CURSOR
▾
Response:
▾

Optional query parameters

  • cursor
    string?
    A pagination cursor.
  • email
    string?
    Filter results by Employee email.

Response data

Returns an array of Employee entities, up to 20 items long.

Scopes required

employees

Get an Employee

Retrieve an individual Employee entity.

GEThttps://api.nicejob.com/v2/employees/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Employee entity if found. Returns a null result otherwise.

Scopes required

employees

Create an Employee

POSThttps://api.nicejob.com/v2/employees
▾
Response:
▾

Request body

  • archived_at
    Date?
  • email
    stringUnique
    The Employee's validated email address.
  • first_name
    string
  • last_name
    string?
  • phone
    string?
    The Employee's validated phone number.
  • position
    string?
    The Employee's position at the Company.

Response data

Returns the new Employee entity.

Scopes required

employees

Update an Employee

Updates an Employee entity. The values you provide will overwrite any previously-existing values on the entity.

POSThttps://api.nicejob.com/v2/employees/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    The Employee entity ID.

Request body

  • archived_at
    Date?
  • email
    string?Unique
    The Employee's validated email address.
  • first_name
    string?
  • last_name
    string?
  • phone
    string?
    The Employee's validated phone number.
  • position
    string?
    The Employee's position at the Company.

Response data

Returns the updated Employee entity, if found. Returns a null result otherwise.

Scopes required

employees

Invoice

The Invoice entity

Properties

  • id
    stringUnique
    The Invoice entity ID.
  • balance
    float
    The outstanding balance of the Invoice.
  • created_at
    Date
    Entity creation date.
  • currency
    string | null
    The currency of the Invoice (Expects an ISO-4217 Currency Code).
  • description
    string | null
    A description of the Invoice.
  • discounts
    Array<object>
    Any discounts applied to the Invoice.
  • discounts[].amount
    float | null
    The amount of the discount.
  • discounts[].description
    string | null
    A description of the discount.
  • discounts[].name
    string | null
    The name of the discount.
  • discounts[].percentage
    float | null
    The rate at which the Invoice is discounted.
  • employee_ids
    Array<string>
    Employees associated with the Invoice.
  • line
    Array<object>
    Any service or item added to the Invoice.
  • line[].amount
    float | null
    The amount of the line item on the Invoice.
  • line[].description
    string | null
    A description of the line item.
  • name
    string | null
  • paid
    boolean
    Whether or not the Invoice has been paid.
  • paid_at
    Date | null
    When the Invoice was paid.
  • person_id
    string | null
  • person_ids
    Array<string>
    The clients' Person entity IDs.
  • status
    Enum<"draft" | "open" | "paid" | "uncollectible" | "void"> | null
  • subtotal
    float | null
    The subtotal of the Invoice before discounts and taxes are applied.
  • tags
    Array<string>
    Custom tags associated with the Invoice.
  • taxes
    Array<object>
    Any taxes applied to the Invoice.
  • taxes[].amount
    float | null
    The amount of the tax.
  • taxes[].description
    string | null
    A description of the tax.
  • taxes[].name
    string | null
    The name of the tax.
  • taxes[].percentage
    float | null
    The rate at which the Invoice is taxed.
  • total
    float
    The total of the Invoice after discounts and taxes are applied.
  • updated_at
    Date
    Entity last-updated date.

List Invoices

Retrieve a paginated list of Invoice entities.

GEThttps://api.nicejob.com/v2/invoices?person_id=$PERSON_ID&cursor=$CURSOR
▾
Response:
▾

Optional query parameters

  • cursor
    string?
    A pagination cursor.
  • person_id
    string?

Response data

Returns an array of Invoice entities, up to 20 items long.

Scopes required

invoices

Get an Invoice

Retrieve an individual Invoice entity.

GEThttps://api.nicejob.com/v2/invoices/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Invoice entity if found. Returns a null result otherwise.

Scopes required

invoices

Create an Invoice

POSThttps://api.nicejob.com/v2/invoices
▾
Response:
▾

Request body

  • id
    stringUnique
    Entity ID
  • balance
    float
  • created_at
    Date
    Entity creation date.
  • currency
    string?
  • description
    string?
  • discounts
    Array<object>
  • discounts[].amount
    float?
  • discounts[].description
    string?
  • discounts[].name
    string?
  • discounts[].percentage
    float?
  • employee_ids
    Array<string>
  • line
    Array<object>
  • line[].amount
    float?
  • line[].description
    string?
  • name
    string?
  • paid
    boolean?
  • paid_at
    Date?
  • person_id
    string?
  • person_ids
    Array<string>
  • status
    Enum<"draft" | "open" | "paid" | "uncollectible" | "void">?
  • subtotal
    float?
  • tags
    Array<string>
  • taxes
    Array<object>
  • taxes[].amount
    float?
  • taxes[].description
    string?
  • taxes[].name
    string?
  • taxes[].percentage
    float?
  • total
    float

Response data

Returns the new Invoice entity.

Scopes required

invoices

Update an Invoice

Updates an Invoice entity. The values you provide will overwrite any previously-existing values on the entity.

POSThttps://api.nicejob.com/v2/invoices/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Request body

  • balance
    float?
  • created_at
    Date
    Entity creation date.
  • currency
    string?
  • description
    string?
  • discounts
    Array<object>
  • discounts[].amount
    float?
  • discounts[].description
    string?
  • discounts[].name
    string?
  • discounts[].percentage
    float?
  • employee_ids
    Array<string>
  • line
    Array<object>
  • line[].amount
    float?
  • line[].description
    string?
  • name
    string?
  • paid
    boolean?
  • paid_at
    Date?
  • person_id
    string?
  • person_ids
    Array<string>
  • status
    Enum<"draft" | "open" | "paid" | "uncollectible" | "void">?
  • subtotal
    float?
  • tags
    Array<string>
  • taxes
    Array<object>
  • taxes[].amount
    float?
  • taxes[].description
    string?
  • taxes[].name
    string?
  • taxes[].percentage
    float?
  • total
    float?

Response data

Returns the updated Invoice entity, if found. Returns a null result otherwise.

Scopes required

invoices

Payment

The Payment entity

Properties

  • id
    stringUnique
    The Payment entity ID.
  • amount
    float
    The amount of of the Payment.
  • amount_refunded
    float | null
    The amount refunded if any.
  • created_at
    Date
    Entity creation date.
  • currency
    string | null
    The currency used to make the Payment (Expects an ISO-4217 Currency Code).
  • description
    string | null
    A description of the Payment.
  • disputed
    boolean
  • employee_ids
    Array<string>
  • invoice_ids
    Array<string>
    Invoices associated with the Payment.
  • person_ids
    Array<string>
    The clients' Person entity IDs.
  • refunded
    boolean
  • status
    Enum<"succeeded" | "pending" | "failed"> | null
  • tags
    Array<string>
  • updated_at
    Date
    Entity last-updated date.

List Payments

Retrieve a paginated list of Payment entities.

GEThttps://api.nicejob.com/v2/payments?id=$ID
▾
Response:
▾

Optional query parameters

  • id
    stringUnique
    Entity ID

Response data

Returns an array of Payment entities, up to 20 items long.

Scopes required

payments

Get a Payment

Retrieve an individual Payment entity.

GEThttps://api.nicejob.com/v2/payments/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Payment entity if found. Returns a null result otherwise.

Scopes required

payments

Create an Payment

POSThttps://api.nicejob.com/v2/payments
▾
Response:
▾

Request body

  • id
    stringUnique
    Entity ID
  • amount
    float
  • amount_refunded
    float?
  • created_at
    Date
    Entity creation date.
  • currency
    string?
  • description
    string?
  • disputed
    boolean?
  • employee_ids
    Array<string>
  • invoice_ids
    Array<string>
  • person_ids
    Array<string>
  • refunded
    boolean?
  • status
    Enum<"succeeded" | "pending" | "failed">?
  • tags
    Array<string>

Response data

Returns the new Payment entity.

Scopes required

payments

Update an Payment

Updates an Payment entity. The values you provide will overwrite any previously-existing values on the entity.

POSThttps://api.nicejob.com/v2/payments/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Request body

  • amount
    float?
  • amount_refunded
    float?
  • created_at
    Date
    Entity creation date.
  • currency
    string?
  • description
    string?
  • disputed
    boolean?
  • employee_ids
    Array<string>
  • invoice_ids
    Array<string>
  • person_ids
    Array<string>
  • refunded
    boolean?
  • status
    Enum<"succeeded" | "pending" | "failed">?
  • tags
    Array<string>

Response data

Returns the updated Payment entity, if found. Returns a null result otherwise.

Scopes required

payments

Person

A Person represents a company client, or customer.

The Person entity

Properties

  • id
    stringUnique
    The Person entity ID.
  • address
    object | null
  • address.address
    string | null
  • address.city
    string | null
  • address.country
    string | null
  • address.state
    string | null
  • address.unit
    string | null
  • address.zip
    string | null
  • blocked
    boolean
    Whether the Person has been blocked from receiving campaign requests.
  • company
    string | null
    The company at which the Person works.
  • created_at
    Date
    Entity creation date.
  • email
    string | nullUnique
    The Person's validated email address.
  • first_name
    string | null
  • initial_source
    string | null
    The initial source of the Person's data.
  • last_name
    string | null
  • lifecycle_stage
    string | null
  • phone
    string | null
    The Person's validated phone number.
  • position
    string | null
    The person's position at their company.
  • tags
    Array<string>
    Custom tags associated with the Person.
  • updated_at
    Date
    Entity last-updated date.

List People

Retrieve a paginated list of Person entities.

GEThttps://api.nicejob.com/v2/people?email=$EMAIL&cursor=$CURSOR
▾
Response:
▾

Optional query parameters

  • cursor
    string?
    A pagination cursor.
  • email
    string?
    Filter results by Person email.

Response data

Returns an array of Person entities, up to 20 items long.

Scopes required

people

Get a Person

Retrieve an individual Person entity.

GEThttps://api.nicejob.com/v2/people/:id
▾
Response:
▾

Response data

Returns the Person entity if found. Returns a null result otherwise.

Scopes required

people

Create a Person

POSThttps://api.nicejob.com/v2/people
▾
Response:
▾

Request body

  • address
    object?
  • address.address
    string?
  • address.city
    string?
  • address.country
    string?
  • address.state
    string?
  • address.unit
    string?
  • address.zip
    string?
  • blocked
    boolean?
    Whether the Person has been blocked from receiving campaign requests.
  • company
    string?
    The company at which the Person works.
  • email
    string?Unique
    The Person's validated email address.
  • first_name
    string?
  • initial_source
    string?
    The initial source of the Person's data.
  • last_name
    string?
  • lifecycle_stage
    string?
  • phone
    string?
    The Person's validated phone number.
  • position
    string?
    The person's position at their company.
  • tags
    Array<string>
    Custom tags associated with the Person.

Response data

Returns the new Person entity.

Scopes required

people

Update a Person

Updates a Person entity. The values you provide will overwrite any previously-existing values on the entity.

POSThttps://api.nicejob.com/v2/people/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    The Person entity ID.

Request body

  • address
    object?
  • address.address
    string?
  • address.city
    string?
  • address.country
    string?
  • address.state
    string?
  • address.unit
    string?
  • address.zip
    string?
  • blocked
    boolean?
    Whether the Person has been blocked from receiving campaign requests.
  • company
    string?
    The company at which the Person works.
  • email
    string?Unique
    The Person's validated email address.
  • first_name
    string?
  • initial_source
    string?
    The initial source of the Person's data.
  • last_name
    string?
  • lifecycle_stage
    string?
  • phone
    string?
    The Person's validated phone number.
  • position
    string?
    The person's position at their company.
  • tags
    Array<string>
    Custom tags associated with the Person.

Response data

Returns the updated Person entity, if found. Returns a null result otherwise.

Scopes required

people

Review

A Review represents a company review on a particular network.

The Review entity

Properties

  • id
    stringUnique
    The Review entity ID.
  • author
    string | null
    The author name on the Review network.
  • author_email
    string | null
  • created_at
    string
    The Review creation date.
  • microsite_url
    string | null
    URL to the review on the Company's NiceJob Microsite.
  • network
    string | null
    The source network.
  • person_id
    string | null
    The related Person ID.
  • rating
    float | null
    The Review rating.
  • source_base_url
    string | null
    Link to the original review source. In order to support review-linking functionality when source_url is not provided
  • source_url
    string | null
    Deeplink URL to the original review at the external source. Some review sources do not support deep-linking to individual reviews and so in this case, the source_url will be null.

List Reviews

Retrieve a paginated list of Review entities.

GEThttps://api.nicejob.com/v2/reviews?id=$ID&person_id=$PERSON_ID
▾
Response:
▾

Optional query parameters

  • id
    stringUnique
    Entity ID
  • person_id
    string?

Response data

Returns an array of Review entities, up to 20 items long.

Scopes required

reviews

Get a Review

Retrieve an individual Review entity.

GEThttps://api.nicejob.com/v2/reviews/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Review entity if found. Returns a null result otherwise.

Scopes required

reviews

ReviewInsights

The ReviewInsights entity provides an aggregate summary of a company's online reviews.

The ReviewInsights entity

Properties

  • average_rating
    float
    The average rating of all of a Company's reviews.
  • network_insights
    Array<object>
  • network_insights[].average_rating
    float
  • network_insights[].network
    string
    Review network name.
  • network_insights[].review_count
    int
  • review_count
    int
    The total number of Company reviews.

Get ReviewInsights

Retrieve the ReviewInsights entity.

GEThttps://api.nicejob.com/v2/review_insights?person_id=$PERSON_ID
▾
Response:
▾

Optional query parameters

  • person_id
    string?
    Filter results by Person.

Response data

Returns the ReviewInsights entity.

Scopes required

review_insights

Visit

Many job management softwares will distinguish between a job and its constituent parts – the visits, or segments, that comprise it. We provide the same functionality here: a Visit entity is the child entity of a Booking.

A Visit has a required booking_id property – therefore the Booking must be created before the Visit. A Booking, meanwhile, does not necessarily have to include Visits.

Note that – unlike with Bookings – a NiceJob user will have to update their Company's Campaign settings should they want a Visit completion to trigger the creation of a CampaignEnrollment. Campaign settings cannot be updated through the API.

If you wish to have a Visit trigger a CampaignEnrollment, consider just using Bookings instead, or notify your users of the necessity to update their NiceJob Campaign settings.

Upon completion, a Visit is to be updated as complete.

The Visit entity

Properties

  • id
    stringUnique
    The Visit entity ID.
  • amount
    float | null
    The payment amount associated with the Visit, in dollars.
  • booking_id
    string
    The Visit entity's parent Booking ID.
  • complete
    boolean
    Whether the work associated with the Visit has been completed.
  • completed_time
    Date | null
    The date the Visit was completed.
  • created_at
    Date
    Entity creation date.
  • employee_ids
    Array<string>
    Employees who worked the Visit.
  • name
    string | null
    A name for the Visit.
  • person_id
    string
    The client's Person entity ID.
  • scheduled_time
    Date | null
    The date the Visit is/was scheduled for.
  • tags
    Array<string>
    Custom tags associated with the Visit.
  • updated_at
    Date
    Entity last-updated date.

List Visits

Retrieve a paginated list of Visit entities.

GEThttps://api.nicejob.com/v2/visits?person_id=$PERSON_ID&cursor=$CURSOR
▾
Response:
▾

Optional query parameters

  • cursor
    string?
    A pagination cursor.
  • person_id
    string?
    Filter results by Person.

Response data

Returns an array of Visit entities, up to 20 items long.

Scopes required

bookings

Get a Visit

Retrieve an individual Visit entity.

GEThttps://api.nicejob.com/v2/visits/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Visit entity if found. Returns a null result otherwise.

Scopes required

bookings

Create a Visit

POSThttps://api.nicejob.com/v2/visits
▾
Response:
▾

Request body

  • amount
    float?
    The payment amount associated with the Visit, in dollars.
  • booking_id
    string
    The Visit entity's parent Booking ID.
  • complete
    boolean?
    Whether the work associated with the Visit has been completed.
  • completed_time
    Date?
    The date the Visit was completed.
  • created_at
    Date
    Entity creation date.
  • employee_ids
    Array<string>
    Employees who worked the Visit.
  • name
    string?
    A name for the Visit.
  • person_id
    string
    The client's Person entity ID.
  • scheduled_time
    Date?
    The date the Visit is/was scheduled for.
  • tags
    Array<string>
    Custom tags associated with the Visit.

Response data

Returns the new Visit entity.

Scopes required

bookings

Update a Visit

Updates a Visit entity. The values you provide will overwrite any previously-existing values on the entity.

POSThttps://api.nicejob.com/v2/visits/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    The Visit entity ID.

Request body

  • amount
    float?
    The payment amount associated with the Visit, in dollars.
  • booking_id
    string?
    The Visit entity's parent Booking ID.
  • complete
    boolean?
    Whether the work associated with the Visit has been completed.
  • completed_time
    Date?
    The date the Visit was completed.
  • created_at
    Date
    Entity creation date.
  • employee_ids
    Array<string>
    Employees who worked the Visit.
  • name
    string?
    A name for the Visit.
  • person_id
    string?
    The client's Person entity ID.
  • scheduled_time
    Date?
    The date the Visit is/was scheduled for.
  • tags
    Array<string>
    Custom tags associated with the Visit.

Response data

Returns the updated Visit entity, if found. Returns a null result otherwise.

Scopes required

bookings

Webhook

NiceJob webhooks allow you to receive a notification whenever a change occurs to a company's data. The process for creating a webhook is as follows:

  1. Create an endpoint on your server which is accessible from our servers.
  2. Create a webhook entity through the NiceJob API where the endpoint_url is the fully-qualified URL of your new endpoint, and specify one or more entity types (subscriptions) with which this webhook is associated. See the subscriptions list below.
  3. Test the webhook using our webhook testing endpoint described below.
A single webhook endpoint can receive one or many subscription types.

A NiceJob webhook is company-independent. Instead, it is linked to your developer account. This means that you only need to establish a single webhook endpoint for all company connections, and not one endpoint for each company connection. This approach makes it much easier to manage your webhooks: for example when changing your webhook subscriptions, or changing a webhook endpoint. An example workflow is as follows:

  1. A Person-related event is published within NiceJob.
  2. NiceJob checks all registered webhooks for those subscribed to the Person entity.
  3. NiceJob then checks that the owner of each subscribed webhook has a valid access token for the affected company with the Person entity in-scope.
  4. For all registered and subscribed and authorized webhooks, a message is published to the registered endpoint.

Webhook authentication

The webhook endpoint is linked to your developer account, and as such does not require OAuth2 user authorization to manage (as defined in the Authentication section above). Thus the webhook endpoint requires an access token provided using the grant_type: "client_credentials" OAuth2 flow as described here.

The access token provided using the client_credentials flow has a limited set of scopes for managing entities associated with your developer account.

POSThttps://api.nicejob.com/oauth/token
▾
Response:
▾
Get client_credentials access token

Generates a client_credentials access token using your client ID and client secret, and the "client_credentials" grant type.

The Webhook Entity

Properties

  • id
    stringUnique
    Webhook ID
  • created_at
    Date
    Entity creation date.
  • endpoint_url
    string
    Endpoint to which relevant webhook messages will be published
  • is_enabled
    boolean
    Is the webhook enabled?
  • secret
    string
    Generated on webhook creation and returned only in the Create Webhook response; used to verify webhook messages
  • subscriptions
    Array<Enum<"Person" | "Job" | "Invoice" | "Conversation" | "Story" | "Photo" | "Campaign" | "CampaignEnrollment" | "Employee" | "Review" | "Case" | "Payment" | "notifications">>
    List of entities associated with this webhook
  • updated_at
    Date
    Entity last-updated date.

Valid subscriptions values are:

  • "Campaign"
  • "CampaignEnrollment"
  • "Case"
  • "Conversation"
  • "Employee"
  • "Invoice"
  • "Job"
  • "Payment"
  • "Person"
  • "Photo"
  • "Review"
  • "Story"

List Webhooks

GEThttps://api.nicejob.com/v2/webhooks?cursor=$CURSOR
▾
Response:
▾

Optional query parameters

  • cursor
    string?
    A pagination cursor.

Response data

Returns an array of Webhook entities, up to 20 items long.

Scopes required

webhooks

Get a Webhook

Retrieve an individual Webhook entity.

GEThttps://api.nicejob.com/v2/webhooks/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Entity ID

Response data

Returns the Webhook entity if found. Returns a 401 HTTP status code if not found.

Scopes required

webhooks

Create a Webhook

Create a new Webhook entity.

POSThttps://api.nicejob.com/v2/webhooks
▾
Response:
▾

Request body

  • endpoint_url
    string?
    Endpoint to which relevant webhook messages will be published
  • subscriptions
    Array<Enum<"Person" | "Job" | "Invoice" | "Conversation" | "Story" | "Photo" | "Campaign" | "CampaignEnrollment" | "Employee" | "Review" | "Case" | "Payment" | "notifications">>
    List of entities associated with this webhook

Response data

Returns the new Webhook entity.

Scopes required

webhooks

Update a Webhook

Updates a Webhook entity.

The subscriptions property of UpdateWebhookInput is immutable. Therefore for an update, you must provide the whole new subscriptions value which will replace the existing subscriptions value.

POSThttps://api.nicejob.com/v2/webhooks/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Webhook ID

Request body

  • endpoint_url
    string?
    Endpoint to which relevant webhook messages will be published
  • is_enabled
    boolean?
    Is the webhook enabled?
  • subscriptions
    Array<Enum<"Person" | "Job" | "Invoice" | "Conversation" | "Story" | "Photo" | "Campaign" | "CampaignEnrollment" | "Employee" | "Review" | "Case" | "Payment" | "notifications">>
    List of entities associated with this webhook

Response data

Returns the updated Webhook entity.

Scopes required

webhooks

Delete a Webhook

Deletes a Webhook entity.

DELETEhttps://api.nicejob.com/v2/webhooks/:id
▾
Response:
▾

Required path parameters

  • id
    stringUnique
    Webhook ID

Response data

Returns the deleted Webhook entity.

Scopes required

webhooks

Webhook requests

Outbound webhook requests are application/json POST requests, with the body data structured as follows:

  • payload
    object
  • payload.company_id
    string
  • payload.entity_id
    string
  • payload.event_code
    string
  • signature
    object
  • signature.signed_payload
    string
  • signature.timestamp
    int

Note that we only provide the entity_id of the entity affected, as well as the event_code, which will confer the entity type. Use the entity endpoints to retrieve the updated entity information.

Signature validation

On webhook creation, a secret will be generated and returned in the response. This is the only time the secret will be shared.

Each Webhook publication will contain a signature which will be composed of two properties: a timestamp and a signed payload. The timestamp will be Unix-format and be appended to the request immediately prior to dispatch.

The signed payload will be a HMAC using the SHA-256 algorithm. In order to validate the signature, one must:

Verify the message came from NiceJob

  1. Serialize the unsigned payload and then concatenate the timestamp. (see clarification below).
  2. Generate the HMAC using the following parameters:
  1. Compare the generated HMAC for equality against the signed_payload property from the received message
It is critical that the order of attributes in the payload are maintained during serialization. Some serialization libraries do not guarantee this, for example the NodeJS JSON library.

Verify the message was not intercepted

The timestamp is generated immediately prior to dispatch. You should compare the timespan between now and the timestamp to see how much time has elapsed and ensure it is within your security tolerances.

Retries

The failure condition for delivery of a Webhook is that we receive a non-2xx HTTP response. When this happens, NiceJob will retry for up to 3 days with an exponential back off. At this point your webhook endpoint will be disabled and we will attempt to inform you via email. Once you have resolved the issue, you can re-enable your webhook using the Update Webhook endpoint by setting the is_enabled property to true.

When invoking a Webhook delivery through the Test Webhook endpoint, there are no retries and your endpoint will not be disabled.

Testing webhooks

For development purposes, we have provided a method of invoking a mock webhook publication for a specific subscription. If you have a webhook registered for the subscription, we will publish to that endpoint with the mock payload.

POSThttps://api.nicejob.com/v2/rpc/test-webhook
▾
Response:
▾

Request body

  • mock_payload
    object
  • mock_payload.company_id
    string
  • mock_payload.entity_id
    string
  • mock_payload.event_code
    string
  • subscription
    Enum<"Person" | "Job" | "Invoice" | "Conversation" | "Story" | "Photo" | "Campaign" | "CampaignEnrollment" | "Employee" | "Review" | "Case" | "Payment" | "notifications">

Response data

Returns a HTTP status code where a 200 indicates a webhook has been found for the provided subscription and it has been successfully queued for publishing.

Scopes required

webhooks