Getting started

This guide provides all the information regarding the new request structure, response, methods and everything else required to make your first API call 🙂

Requirements

The following requirements are essential for you to successfully start interacting with the Tulip platform:

  • Obtain an API Key or Obtain OAuth2 Client Credentials
  • Install your choice of IDE or third-party tool to make API calls. We recommend Postman for working with Tulip’s API service:
    • Postman: HTTP client software for testing web services; recommended for testing, capturing results, and managing related workflows.

Understanding Request Structure

HTTP Request URL

Any request over HTTP must name the HTTP method, the endpoint and the protocol (HTTP/1.1).

HTTP Request Headers

Authorization

Every API request over HTTP must specify the authentication method (Bearer) followed by a valid, Tulip-issued bearer token (redirect URL) as a single line in the HTTP header:

Authorization: Bearer <API Key>
Authorization: Bearer <OAuth 2.0 Access Token>

More about Authentication here.

Content Type

All PUT and POST endpoints accept JSON data, set the content type in header to:

Content-Type: application/json

Unicode Support

There is support for Unicode encoding. To make sure incoming content is handled as UTF-8, send this header with your request:

Content-Type: application/json; charset=UTF-8

Note: Encoding errors will generally return the 400 error code, with the error “Request body JSON couldn’t be parsed into an array.”

HTTP Request Body and Passing Data in Requests

There are 4 ways to pass data into a API request:

  1. Header Parameters - parameters included in the request header, usually related to authorization (API Key) and content-type
  2. Path parameters - Parameters within the path of the endpoint. In the API specification , they’re denoted with ../:value/..
  3. Query string parameters - Parameters in the query string of the endpoint, after the ? separator.
  4. Request body parameter - Parameters included in the request body. Always submitted as JSON. The JSON object contains key-value pairs and may include multiple levels of nesting.

These endpoints use JSON and its inherent ability to store business data as objects and stream that data, as required, in text format for singleton records and for bulk data.

JSON (JavaScript Object Notation):

[
    {"id":1,"name":"Alice"},
    {"id":2,"name":"Bob"},
    {"id":3,"name":"Carol"}
]

HTTP Request Methods

The following HTTP methods are supported:

GET (Fetching)

Fetching single entity by UUID:

GET crm/customers/<UUID>

Example: Fetch (list) all the entities:

GET crm/customers

Searching for an entity or entities based on query parameters:

GET crm/customers/search

POST (Create)

Creating a single entity:

POST crm/customers

Creating multiple entities:

POST crm/customers/bulk

PUT (Upsert)

Updating entities based on externalId (provided in request body). If the entity does not exist, then create it, otherwise update.

PUT crm/customers

PUT (Update)

Update entity based on UUID:

PUT crm/customers/<UUID>

DELETE (Remove)

There are very few DELETE routes in Core API. Many entities cannot be deleted (this is by design).

Entities can be disabled, or invalidated, using a PUT method to change the status_id or disabled property of that entity or entities.

Making an API call

API calls use the following convention:

https://cluster/api/{verion-date}/route

Replace:

  • cluster: with your actual cluster address (e.g. https://tulip-prod-na-tenant.tulipretail.com)

  • version-date: version date of the API you would like to use. Note: The new standard of Core API endpoints are only served with version date: 2022-08 and later. For older standard endpoints please refer use 2022-04.

  • route: API route as documented in the API reference using version 2022-08 in drop down.

Example cURL Request:

curl --X --request GET 'https://cluster/api/2022-08/crm/customers' \
--header 'Content-Type: application/json; charset=UTF-8', `Authorization: Bearer INSERT_TOKEN_HERE'

Error Response Object and Structure

Response Body will always contain an errors key at the root of the response body. The errors key can either be null or an array of Error. If the API call was unsuccessful, the errors key and fields inside will be populated with important information regarding the error and tips on how to resolve.


{
  "errors":  [{
    "message":"Could not create/update resource: Missing field externalId", # User-friendly message
    "errorCode":"invalidResourceMissingRequiredFields", # Specific error code
    "moreInfo":"Find more info at docs.tulip.com/v3-api/errors" # Link to documentation if applicable
  }]
}

As shown, the errors key will give you a user-friendly message , errorCode , and moreInfo containing link to documentation to troubleshoot the error.

Document References: Errors object and Troubleshooting Errors.

← Customer Merge
Authentication →