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.
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 endpoint | https://api.nicejob.com/oauth/authorize |
| Token endpoint | https://api.nicejob.com/oauth/token |
| Revocation endpoint | https://api.nicejob.com/oauth/revoke |
| Introspection endpoint | https://api.nicejob.com/oauth/introspect |
The 3 steps to obtain an access token are thus:
REDIRECT/oauth/authorizeGain the user's consent by redirecting them to the authorization endpoint. We then redirect the user back to your <code>redirect_uri</code>, with the authorization code attached as a query parameter.
POST/oauth/tokenPOST/oauth/tokenWith 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 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 tokens do not expire.
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.
Alpha warning: Token introspection is not yet available.
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.
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.
The NiceJob API expects incoming requests to be in JSON format, with a Content-Type: application/json header.
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.
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.
Any successful API request (status 200) will receive, in response, a JSON object with the following fields:
type: DEFAULT_RESPONSE — See live API documentation for full schema details.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.
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.
type: Job — See live API documentation for full schema details.Retrieve a paginated list of Booking entities.
GET/v2/bookingsReturns an array of Booking entities, up to 20 items long.
Retrieve an individual Booking entity.
GET/v2/bookings/:idReturns the Booking entity if found. Returns a null result otherwise.
POST/v2/bookingsReturns the new Booking entity.
Updates a Booking entity. The values you provide will overwrite any previously-existing values on the entity.
POST/v2/bookings/:idReturns the updated Booking entity, if found. Returns a null result otherwise.
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.
type: Case — See live API documentation for full schema details.Retrieve a paginated list of Case entities.
GET/v2/casesReturns an array of Case entities, up to 20 items long.
Retrieve an individual Case entity.
GET/v2/cases/:idReturns the Case entity if found. Returns a null result otherwise.
POST/v2/casesUpdates a Case entity. The values you provide will overwrite any previously-existing values on the entity.
POST/v2/cases/:idReturns the updated Case entity, if found. Returns a null result otherwise.
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.
type: Campaign — See live API documentation for full schema details.Retrieve a list of Campaign entities.
GET/v2/campaignsReturns an array of Campaign entities.
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.
type: CampaignEnrollment — See live API documentation for full schema details.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.
POST/v2/campaign_enrollmentsReturns the new CampaignEnrollment entity, if successfully created.
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.
type: Company — See live API documentation for full schema details.Retrieve the access token-bound Company entity.
GET/v2/companyReturns the Company entity to which the access token is bound.
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.
type: Employee — See live API documentation for full schema details.Retrieve a paginated list of Employee entities.
GET/v2/employeesReturns an array of Employee entities, up to 20 items long.
Retrieve an individual Employee entity.
GET/v2/employees/:idReturns the Employee entity if found. Returns a null result otherwise.
POST/v2/employeesinput: CreateEmployeeInput — See live API documentation for full schema details.Returns the new Employee entity.
Updates an Employee entity. The values you provide will overwrite any previously-existing values on the entity.
POST/v2/employees/:idReturns the updated Employee entity, if found. Returns a null result otherwise.
type: Invoice — See live API documentation for full schema details.Retrieve a paginated list of Invoice entities.
GET/v2/invoicesReturns an array of Invoice entities, up to 20 items long.
Retrieve an individual Invoice entity.
GET/v2/invoices/:idReturns the Invoice entity if found. Returns a null result otherwise.
POST/v2/invoicesReturns the new Invoice entity.
Updates an Invoice entity. The values you provide will overwrite any previously-existing values on the entity.
POST/v2/invoices/:idReturns the updated Invoice entity, if found. Returns a null result otherwise.
type: Payment — See live API documentation for full schema details.Retrieve a paginated list of Payment entities.
GET/v2/paymentsReturns an array of Payment entities, up to 20 items long.
Retrieve an individual Payment entity.
GET/v2/payments/:idReturns the Payment entity if found. Returns a null result otherwise.
POST/v2/paymentsReturns the new Payment entity.
Updates an Payment entity. The values you provide will overwrite any previously-existing values on the entity.
POST/v2/payments/:idReturns the updated Payment entity, if found. Returns a null result otherwise.
A Person represents a company client, or customer.
type: Person — See live API documentation for full schema details.Retrieve a paginated list of Person entities.
GET/v2/peopleReturns an array of Person entities, up to 20 items long.
Retrieve an individual Person entity.
GET/v2/people/:idReturns the Person entity if found. Returns a null result otherwise.
POST/v2/peopleReturns the new Person entity.
Updates a Person entity. The values you provide will overwrite any previously-existing values on the entity.
POST/v2/people/:idReturns the updated Person entity, if found. Returns a null result otherwise.
A Review represents a company review on a particular network.
type: ReviewResponseExternal — See live API documentation for full schema details.Retrieve a paginated list of Review entities.
GET/v2/reviewsReturns an array of Review entities, up to 20 items long.
Retrieve an individual Review entity.
GET/v2/reviews/:idReturns the Review entity if found. Returns a null result otherwise.
The ReviewInsights entity provides an aggregate summary of a company's online reviews.
type: ReviewInsightsResponse — See live API documentation for full schema details.Retrieve the ReviewInsights entity.
GET/v2/review_insightsReturns the ReviewInsights entity.
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.
type: Visit — See live API documentation for full schema details.Retrieve a paginated list of Visit entities.
GET/v2/visitsReturns an array of Visit entities, up to 20 items long.
Retrieve an individual Visit entity.
GET/v2/visits/:idReturns the Visit entity if found. Returns a null result otherwise.
POST/v2/visitsUpdates a Visit entity. The values you provide will overwrite any previously-existing values on the entity.
POST/v2/visits/:idReturns the updated Visit entity, if found. Returns a null result otherwise.
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:
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.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:
Person-related event is published within NiceJob.Person entity.Person entity in-scope.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.
POST/oauth/tokentype: Webhook — See live API documentation for full schema details.Valid subscriptions values are:
"Campaign""CampaignEnrollment""Case""Conversation""Employee""Invoice""Job""Payment""Person""Photo""Review""Story"GET/v2/webhooksReturns an array of Webhook entities, up to 20 items long.
Retrieve an individual Webhook entity.
GET/v2/webhooks/:idReturns the Webhook entity if found. Returns a 401 HTTP status code if not found.
Create a new Webhook entity.
POST/v2/webhooksReturns the new Webhook entity.
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.
POST/v2/webhooks/:idReturns the updated Webhook entity.
Deletes a Webhook entity.
DELETE/v2/webhooks/:idReturns the deleted Webhook entity.
Outbound webhook requests are application/json POST requests, with the body data structured as follows:
type: WebhookMessage — See live API documentation for full schema details.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.
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:
secret property (shared on webhook creation)signed_payload property from the received messageIt 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.
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.
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.
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.
POST/v2/rpc/test-webhooktype: TestWebhookInput — See live API documentation for full schema details.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.