ii V2 API - Frequently Asked Questions (FAQ)

FAQ Question for Consideration

How do you authenticate with the API?
How do I request API credentials or keys?
Which IDs are static and which can change?
How do I create or update a job or booking?
How do I filter API results?
How do I batch requests to avoid timeouts?
How do I retrieve Additional References and Requirements?
Can I access Rate Plans and Financial Data?
Why does my PUT request return a 500 error even when the update succeeds?
What endpoints are unavailable or unsupported?
How do I pull dropdown options for Additional Requirements?
How can I avoid overloading the API with scripts?
What error codes should I expect and how do I troubleshoot them?
What are the API rate limits and how are they enforced?
Does the API support webhooks for real-time updates?
How do I use pagination effectively with list endpoints?
Can I expand related resources in a single request?
How do I handle date and time fields in the API?
What’s the difference between PUT, PATCH, and POST in this API?
Does the API support bulk operations (create/update multiple records at once)?
How do I report bugs in the API?

1. How do I authenticate with the API?

The v2 API uses token-based authentication.

First, request a token using your client credentials. Then, include the token in all subsequent requests with the Authorization:

Bearer <token> header.
Request:
POST /ii/api/v2/auth
Content-Type: application/json
{
"subject": "your_apiKey",
 "secret": "your_apiSecret"}
Response:
{
"accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJzd...",
 "refreshToken": #z@4FB(io5ptAF1(WwYdBQqL...
}

2. How do I request API credentials or keys?

API credentials are issued by the Boostlingo Interpreter Intelligence Development team. You may request Production Keys via the II Support Team. Keys can be revoked or rotated for security.ID

3. Which IDs are static and which can change?

Entity IDs like Reference, Language, Location, and Requestor are immutable. Attributes may change, but IDs do not.

Example:

{
  "id": 12345,
  "language": "Spanish",
  "location": "Chicago"
}

Even if language or location updates, ID remains the same.

4. How do I create or update a job or booking?

Steps

Create Job: POST /visit
Update Job: PUT /visit/{id}
For Job specific actions, use PUT /visit/{id}.

Example of a minimum job creation payload:

{
  "billingCustomer": {
    "id": {{customer_id}}
  },
  "billingLocation": {
    "id": {{billingLocationId}}
  },
  "bookingDate": "{{currentDate}}",
  "bookingMode": {
    "id": 1
  },
  "client": {
    "id": {{client_id}}
  },
  "company": {
    "id": {{company_id}}
  },
  "consumer": {
    "id": {{consumer_id}}
  },
  "customer": {
    "id": {{customer_id}}
  },
  "expectedEndDate": "{{expectedEndDate}}",
  "expectedStartDate": "{{expectedStartDate}}",
  "language": {
    "id": 41
  },
  "location": {
    "id": {{serviceLocationId}}
  },
  "notes": "{{notes}}",
  "requestor": {
    "id": {{requestor_id}}
  },
  "timeZone": "America/Los_Angeles"
}

5. How do I filter API results?

Most endpoints returning a list of items support parsing a filters structure to get only the data of interest. This structure is expected to be sent in a query param called filters and is a URL-encoded JSON.

As an example, if you want to retrieve all interpreters that were born before 01/01/1990, the JSON structure will look like:

{
    "groupOp": "AND",
    "rules": [
        {
            "op": "lt",
            "field": "dateOfBirth",
            "data": "1990-01-01T00:00:00Z",
            "type": "date"
        }
    ]
}

and the request will look like:

curl 
--location 'https://<base url>/ii/api/v2/contact?filters=%7B%22groupOp%22%3A%22AND%22%2C%22rules%22%3A%5B%7B%22op%22%3A%22lt%22%2C%22field%22%3A%22dateOfBirth%22%2C%22data%22%3A%221990-01-01T00%3A00%3A00Z%22%2C%22type%22%3A%22date%22%7D%5D%7D' 
--header 'Accept: application/json' whose
--header 'Authorization: Bearer x.y.z'

You can have multiple rules and even nest operators if you have a more complex use case. This is an example for fetching all interpreters that were born before 01/01/1990 and whose first name is "John" or their last name is "Doe":

{
    "groupOp": "AND",
    "rules": [
        {
            "op": "lt",
            "field": "dateOfBirth",
            "data": "1990-01-01T00:00:00Z",
            "type": "date"
        },
        {
            "groupOp": "OR",
            "rules": [
                {
                    "op": "eq",
                    "field": "firstName",
                    "data": "John"
                },
                {
                    "op": "eq",
                    "field": "lastName",
                    "data": "Doe"
                }
            ]
        }
    ]
}

and its corresponding request:

curl 
--location 'https://<base url>/ii/api/v2/contact?filters=%7B%22groupOp%22%3A%22AND%22%2C%22rules%22%3A%5B%7B%22op%22%3A%22lt%22%2C%22field%22%3A%22dateOfBirth%22%2C%22data%22%3A%221990-01-01T00%3A00%3A00Z%22%2C%22type%22%3A%22date%22%7D%2C%7B%22groupOp%22%3A%22OR%22%2C%22rules%22%3A%5B%7B%22op%22%3A%22eq%22%2C%22field%22%3A%22firstName%22%2C%22data%22%3A%22John%22%7D%2C%7B%22op%22%3A%22eq%22%2C%22field%22%3A%22lastName%22%2C%22data%22%3A%22Doe%22%7D%5D%7D%5D%7D' 
--header 'Accept: application/json' 
--header 'Authorization: Bearer x.y.z'

6. How do I batch requests to avoid timeouts?

Large requests (>6 months) may time out. Use pagination or date slicing.

Request (with date range):

GET /ii/api/v2/jobs?startDate=2025-01-01&endDate=2025-02-01&limit=100
Authorization: Bearer <token>

7. How do I retrieve Additional References and Requirements?

These appear in Customer and Booking payloads. Use the expand parameter to include.

Request:
GET /ii/api/v2/bookings/123?expand=additionalRequirements,additionalReferences
Authorization: Bearer <token>
Response:
{
  "id": 123,
  "additionalRequirements": ["ASL Certified"],
  "additionalReferences": ["Case #4567"]
}

8. Can I access Rate Plans and Financial Data?

Currently, we provide no access to rate plan info; we only provide access to the Invoice, Payments, Credit memos and payable item endpoints.

9. Why does my PUT request return a 500 error even when the update succeeds?

The server may process valid fields but reject extra/misformatted fields. Always match the Swagger schema.

Bad Request Example:

PUT /ii/api/v2/jobs/789
{
  "status": "completed",
  "extraField": "notAllowed"
}

Response: 500 Internal Server Error (though status updated).

10. What endpoints are available?

This list encompasses most of the available endpoints

DELETE /ii/api/v2/visit/{visitId} - delete a visit
GET /ii/api/v2/booking/{id}/payableItem - list payableItems by booking
GET /ii/api/v2/contact/{id} - list a contact
GET /ii/api/v2/customer/{id}/address - list a customer address
GET /ii/api/v2/deletionHistory - list deleted history (Booking)
GET /ii/api/v2/deletionHistory - list deleted history (Visit)
GET /ii/api/v2/deletionHistory/{id} - list deleted history by id
GET /ii/api/v2/invoice - list invoices
GET /ii/api/v2/invoice/{id} - list an invoice
GET /ii/api/v2/invoice/{id}/payableItem - list an invoice payableItem
GET /ii/api/v2/joboffer - list job offers
GET /ii/api/v2/joboffer/{id} - list a job offer
GET /ii/api/v2/payment - list payments
GET /ii/api/v2/payment/{id}/payableItem - list a payment
GET /ii/api/v2/reference-code-config
GET /ii/api/v2/reference-code-auto-complete
PATCH /ii/api/v2/payment/{id} - updates a payment
POST /ii/api/v2/contact - create a contact
POST /ii/api/v2/customer - create a customer
POST /ii/api/v2/invoice - create an invoice
POST /ii/api/v2/invoice/{id}/payableItem - creates a payable item for invoice
POST /ii/api/v2/visit - create a job
PUT /ii/api/v2/booking/{id} - update a booking
PUT /ii/api/v2/booking/{id}/close
PUT /ii/api/v2/booking/{id}/unverify - unverify a booking
PUT /ii/api/v2/booking/{id}/verify - verify a booking
PUT /ii/api/v2/contact/{id} - update a contact
PUT /ii/api/v2/visit/{id} - update a visit

11. How do I pull dropdown options for Additional Requirements?

GET /ii/api/v2/reference-code-config
GET /ii/api/v2/reference-code-auto-complete

12. How can I avoid overloading the API with scripts?

Follow best practices:

Use limit/offset for pagination.
Respect API rate limits (throttle requests).
Batch requests instead of looping indefinitely.

13. What error codes should I expect, and how do I troubleshoot them?

The API follows standard HTTP status codes:

200 OK → Successful request
201 Created → Resource successfully created
400 Bad Request → Invalid payload or parameters
401 Unauthorized → Missing/invalid token
403 Forbidden → Insufficient permissions
404 Not Found → Resource doesn’t exist
500 Internal Server Error → Server-side error

Example (Unauthorized):

GET /ii/api/v2/jobs
Authorization: Bearer invalid_token

Response:

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

14. What are the API rate limits and how are they enforced?

While rate limits vary by environment, requests beyond allowed thresholds return 429 Too Many Requests. Always implement exponential backoff.

Example Response:

{
  "error": "Too Many Requests",
  "retry_after": 60
}

15. Does the API support webhooks for real-time updates?

Currently, v2 does not provide webhook subscriptions. All updates must be retrieved via polling endpoints such as /jobs or /bookings.

16. How do I use pagination effectively with list endpoints?

We can use the following query params:

filters: The filters encapsulate the specific search criteria that are being searched for.
Filters have two nested objects: groupOp and rules.
page: The page number to return. A value of 1 will return the 1st page, a value of 2 will return the 2nd page.

The search response will contain three parameters that are related to this parameter and can be used to support pagination: pageSize, count, and numPages.

Rows: The number of records to return in this request. A value of 10 will return 10 results (if available) in the response.

The search response will contain three parameters that are related to this parameter and can be used to support pagination: pageSize, count, and numPages.

Default value: 25
- sidx: The field on the entity to order the results by.
Default value: createdDate
- sord: The order to return results in. Possible options are "asc" or "desc"
Default value: desc

17. Can I expand related resources in a single request?

We don't have an expand option when using our V2 API. However, we do have 2 Global API serialization options.

The embedded query parameter allows you to specify which related resources should be included in the response. It is used to retrieve additional data related to the main resource being requested. For example, if you have an API endpoint for retrieving a user's details, you can use the embedded query parameter to also include the user's associated posts or comments.

Example usage:

GET /ii/api/v2/contact/1?embedded=emails,numbers

Fields Query Parameter

The field query parameter allows you to specify which fields of the resource should be included in the response. It is used to retrieve a subset of fields instead of the entire resource. This can be useful when you only need specific information and want to reduce the payload size.

Example usage:

GET /ii/api/v2/contact/1?fields=firstName,lastName

18. How do I handle date and time fields in the API?

All dates/times use ISO 8601 UTC format (YYYY-MM-DDTHH:mm:ssZ). Always convert to UTC before sending.

Example Request:

POST /ii/api/v2/jobs
{
  "startTime": "2025-09-01T15:00:00Z"
}

19. What’s the difference between PUT, PATCH, and POST in this API?

Information

POST: Create new resource
PUT: Replace/update an existing resource by ID
PATCH: Partial update (if supported — check endpoint schema)

Example PUT Request:

PUT /ii/api/v2/jobs/789
{
  "status": "completed"
}

20. Does the API support bulk operations (create/update multiple records at once)?

No dedicated bulk endpoints exist in v2. Each resource must be created individually with POST. Developers should script batched requests.

21. How do I report bugs in the API?

Use your Support channel (ticketing system) to log issues. Include:

Endpoint used
Request payload
Response/error received

Search