Introduction

The Stitch Import API enables you to push arbitrary data from a source to Stitch. The Import API acts as a receiving point for data that is sent to Stitch. The Import API will ‘listen’ for new data, which is then processed by Stitch as it’s received.

This API is a RESTful, method-oriented API that allows you to push data from a source (including those Stitch doesn’t currently have an integration for) and send it to Stitch. Each endpoint uses standard HTTP verbs like GET and POST, and will return standard HTTP response codes to indicate request status or errors.

The API is built to accept JSON requests and to return JSON in all responses, including errors.

API functionality

Using the Import API, you can:

  • Push data from a source to Stitch
  • Check the status of the Import API
  • Validate push requests and batches without persisting them to Stitch

Accessing the API

Anyone with a Stitch account can use the Import API. If you don’t currently have an account, sign up for a free trial here.

After you create a Stitch account, refer to the Managing Import API access tokens in Stitch guide for instructions on generating an Import API access token in the Stitch app.

Note: If you’re a Stitch Connect user, refer to the Managing Import API access tokens via the Connect API guide.

API support

While the Import API is a certified Stitch integration, using it does require some technical knowledge. This means that Stitch will address bugs and issues with the API that are within Stitch’s infrastructure, but Stitch doesn’t provide assistance for building or maintaining the scripts that send data to the API.

The table below provides some examples of the types of requests Stitch will and will not provide assistance for.

Stitch Support can assist with: Stitch Support does not assist with:
  • Identifying and reporting Import API outages
  • Identifying and resolving issues within Stitch
  • Retrieving API access tokens
  • Writing scripts
  • Data typing in requests
  • Troubleshooting scripts or API requests
  • Troubleshooting open source scripts that use the Import API, e.g. Google Sheets
  • Troubleshooting or using open source libraries for the Import API

Refer to the Import API guides and resources for assistance when developing and testing your script.

Additionally, ask the Stitch Community if you’re still stuck.


Authentication

The Import API uses an API access token to authenticate requests. Import API access tokens can be generated and managed in the Integration Settings page for any Import API integration in your Stitch account. If you’re a Stitch Connect user, you can also use the Connect API to create Import API sources and manage their access tokens.

Authentication is performed via bearer auth, where your Import API access token is provided in the header of your request as -H 'Authorization: Bearer at_<IMPORT_API_ACCESS_TOKEN>'.

Your API access token has write access to the Stitch integration schema or dataset in your destination. Because of this, API access tokens should be treated like passwords - don’t share them in publicly accessible places like Stackoverflow, GitHub, etc. Note: You also shouldn’t share your API access token with Stitch Support. If sharing requests, remember to redact the API access token before sending.

If an API access token is ever lost or compromised, you can revoke it and create a new token.

Refer to the Managing Import API access tokens in Stitch guide for more info.

Stitch client IDs

For some the Push and Validate push request endpoints, you’ll need to include your Stitch client ID for every record contained in a request body. Your Stitch client ID is the unique ID associated with your Stitch account.

POST /v2/import/push
curl -X "POST" "https://api.stitchdata.com/v2/import/push" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'[
    {
      "client_id": 7723,              /* Stitch client ID */
      "table_name": "customers",
      "sequence": 1565880017,
      "data": {
        "id": 4,
        "name": "Beamo"
      },
      "key_names": [
        "id"
      ],
      "action": "upsert"
    },
    {
      "client_id": 7723,              /* Stitch client ID */
      "table_name": "orders",
      "sequence": 1565838645,
      "key_names": [
        "order_id"
      ],
      "data": {
        "order_id": 561,
        "customer_id": 4
      },
      "action": "upsert"
    }
  ]'

To locate your client ID, sign into your Stitch account and look at the URL. The client ID is the four to six-digit number between client and pipeline in the URL.

For example: If the URL is https://app.stitchdata.com/v2/client/7723/pipeline/connections, the client ID would be 7723.

A client ID may have multiple API access tokens associated with it, but an API access token will only ever be associated with a single client ID.


Response Codes

The API will attempt to return HTTP status codes to indicate the success or failure of a request sent to the API.

In general:

  • Codes in the 2xx range indicate success
  • Codes in the 4xx range indicate an error with the request, such as an invalid API access token, missing client ID, malformed request body, etc.
  • Codes in the 5xx range indicate an issue with Stitch. Persistent 5xx codes may indicate an outage, which you can monitor on Stitch’s status page.

Your application should handle each of the following statuses gracefully:

Code Text Description
200

OK

Success! New data was added as a result of the request.

201

Created

The request was accepted and will be processed later. New data will be added once the request is processed.

202

Accepted

The request was accepted, but cannot currently be processed due to an internal error. Data will be automatically re-processed.

400

Bad Request

The request includes malformed JSON/Transit, did not provide an array of records, or contains more than 20,000 records.

401

Unauthorized

The request doesn’t have a valid API access token. Verify your token is correct and re-try the request, or generate a new token and then re-try.

403

Forbidden

The request had a valid API token, but is not permitted. The client_id in the request body may be incorrect.

404

Not Found

Potential causes:

  • The URI requested is invalid
  • Method is not allowed by the endpoint
405

Method Not Allowed

The request has an HTTP method that is not supported by the endpoint. POST and GET are supported by the Import API.

413

Request Entity Too Large

The size of the request body exceeded 20MB.

415

Unsupported Media Type

The content header of the request didn’t specify a supported media type, or specified an unsupported media type.

The Import API supports JSON (application/json) and Transit (application/transit+json). Note: Only the Push and Validate push request endpoints accept Transit.

422

Unprocessable Entity

The request body is missing a required argument.

503

Service Unavailable

The Import API is experiencing problems. Try again later.

504

Gateway Timeout

The Import API couldn’t process the request in time due to an internal error. Try again later.

Response and error message formats

The API will return responses - successful or errors - in JSON format. Below are descriptions and examples of each type of response.

Response message formats

For successful responses (codes in the 2xx range) the API will return messages as a JSON object:

{
  "status": "OK",
  "message": "Batch Accepted!"
}

In the Import API documentation, this is referred to as a Batch Status object.

Error message formats

For error responses (codes in the 4xx range), the API will return error messages in JSON format. In the Import API documentation, this is referred to as an Error object.

Some error messages may be returned as strings:

Content-Type must be application/json

While others may be JSON objects:

{
  "status": "ERROR",
  "error": "Forbidden",
  "errors": {
    "error": "Access token is not associated with this client."
  }
}

Error message text

The text in error messages will vary by root cause and endpoint.

Each endpoint section contains a list of the errors specific to that endpoint. Refer to the documentation for the endpoint for specifics on errors, their possible causes, and the messages the API will return.


Versioning

When we make backwards-incompatible changes to the API, we release a new version. The current version of the Import API is 2.


Methods

API Status

An object describing the status of the Import API at the time a request is sent.

Endpoints

GET Get Import API status

Determines if the Import API is operating correctly. This endpoint doesn’t require any authentication.


OBJECT

The API Status object

An object describing the status of the Import API at the time a request is sent.

name
STRING

This will always be pipeline.gate.

version
STRING

Stitch internal field.

revision
STRING

Stitch internal field.

status
STRING

The status of the Import API at the time of the request.

reason
STRING

If applicable, the reason for the status.

Example object
{
  "name": "pipeline.gate",
  "version": "0.3.3-SNAPSHOT",
  "revision": "a154360ad8c43182965049dbf6239aa7c1f3c84d",
  "status": "OK",
  "reason": null
}

GET

Get Import API status

Determines if the Import API is operating correctly. This endpoint doesn’t require any authentication.

Resource list
Request Method

GET

Resource URL

/v2/import/status

Authorization

Not required.

Request Header

Not required.

See the Request tab below for example requests.

Request Body

The request body must be valid JSON or Transit and contain the required arguments.

Response Format

Whether the request succeeds or fails, the API will return JSON.

Returns

If successful, the API will return a 200 OK status and an API status object.

GET /v2/import/status
curl "https://api.stitchdata.com/v2/import/status"
Response for GET /v2/import/status
{
  "name": "pipeline.gate",
  "version": "0.3.3-SNAPSHOT",
  "revision": "a154360ad8c43182965049dbf6239aa7c1f3c84d",
  "status": "OK",
  "reason": null
}


Batch

An object containing a table name, a table schema, and message objects representing records to be pushed to Stitch.

Endpoints

POST Create a batch

Pushes data for a specified table to Stitch.


OBJECT

The Batch object

An object containing a table name, a table schema, and message objects representing records to be pushed to Stitch.

table_name
STRING

The name of the destination table the data is being pushed to. Table names must be unique in each destination schema, or loading issues will occur.

Note: The number of characters in the table name should be within the destination’s allowed limits or data will rejected.

schema
OBJECT (SCHEMA)

A Schema object containing the JSON schema describing the record(s) in the Message object’s data property.

Records must conform to this schema or an error will be returned when the request is sent.

messages
ARRAY (MESSAGE)

An array of Message objects, each representing a record to be upserted into the table.

key_names
ARRAY

An array of strings representing the Primary Key fields in the source table. Note: A value must be provided, but it may be an empty list to indicate that the source table doesn’t have a Primary Key.

If fields are provided, they must comply with the following:

  1. Each field in the list must be the name of a top-level property defined in the Schema object. Primary Key fields cannot be contained in an object or an array.
  2. Fields in the list may not be null in the source.
  3. If a field is a string, its value must be less than 256 characters.

All fields included in key_names must be present in the Schema object and every Message object in the request.

Example object
{
  "table_name": "customers",
  "schema": {
    "properties": {
      "id": {
        "type": "integer"
      },
      "name": {
        "type": "string"
      },
      "age": {
        "type": "integer"
      },
      "has_magic": {
        "type": "boolean"
      }
    }
  },
  "messages": [
    {
      "action": "upsert",
      "sequence": 1565880017,
      "data": {
        "id": 1,
        "name": "Finn",
        "age": 15,
        "has_magic": false
      }
    }
  ],
  "key_names": [
    "id"
  ]
}

POST

Create a batch

Pushes a record or multiple records for a specified table to Stitch. Each request to this endpoint may only contain data for a single table.

When data for a table is pushed for the first time, Stitch will create the table in the destination in the specified integration schema.

How data is loaded during subsequent pushes depends on:

  1. The loading behavior types used by the destination. Stitch supports Upsert and Append-Only loading.
  2. Whether the key_names property specifies Primary Key fields. If Primary Keys aren’t specified, data will be loaded using Append-Only loading.

Refer to the Understanding loading behavior guide for more info and examples.

Structuring request body data

Refer to the Structuring data for the Import API guide for instructions and examples.

Resource list
Request Method

POST

Resource URL

/v2/import/batch

Authorization

Required. The request header must contain Authorization and your Import API access token.

Request Header

The request header must contain the following:

  • Authorization: Must specify Bearer Auth, e.g. Bearer: <ACCESS_TOKEN>

  • Content-Type: Must specify JSON, e.g. application/json

See the Request tab below for example requests.

Request Body

The request body must be valid JSON and contain the required arguments.

The request body must also comply with the following:

  • Must contain all required arguments.

  • Cannot exceed 20MB in size.

  • Each data object in the request body must contain between 1 and 20,000 records.

  • Each data object in the request body cannot exceed 10,000 individual data points.

  • Must contain data only for a single table.

Response Format

Whether the request succeeds or fails, the API will return JSON.

Errors

See the Errors tab, below.

Arguments

This endpoint accepts the following parameters:

table_name
STRING
REQUIRED

The name of the destination table the data is being pushed to. Table names must be unique in each destination schema, or loading issues will occur.

Note: The number of characters in the table name should be within the destination’s allowed limits or data will rejected.

schema
OBJECT (SCHEMA)
REQUIRED

A Schema object containing the JSON schema describing the record(s) in the Message object’s data property.

Records must conform to this schema or an error will be returned when the request is sent.

messages
ARRAY (MESSAGE)
REQUIRED

An array of Message objects, each representing a record to be upserted into the table.

key_names
ARRAY
OPTIONAL

An array of strings representing the Primary Key fields in the source table. Stitch use these Primary Keys to de-dupe data during loading. If not provided, the table will be loaded in an append-only manner.

Note: If included, a value must be provided. However, it may be an empty list to indicate that the source table doesn’t have a Primary Key.

If fields are provided, they must adhere to the following:

  1. Each field in the list must be the name of a top-level property defined in the Schema object. Primary Key fields cannot be contained in an object or an array.
  2. Fields in the list may not be null in the source.
  3. If a field is a string, its value must be less than 256 characters.

All fields included in key_names must be present in the Schema object and every Message object in the request.

Returns

If successful, the API will return a 2xx status and a Batch status object:

  • 201 - The request was accepted and will be processed later. New data will be added once the request is processed.

  • 202 - The request was accepted, but cannot currently be processed due to an internal error. Data will be automatically re-processed.

Requests for POST /v2/import/batch

Pushing a single record
curl -X "POST" "https://api.stitchdata.com/v2/import/batch" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'{
    "table_name": "customers",
    "schema": {
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer"
        },
        "has_magic": {
          "type": "boolean"
        },
        "modified_at":{
            "type":"string",
            "format":"date-time"
         }
      }
    },
    "messages": [
      {
        "action": "upsert",
        "sequence": 1565880017,
        "data": {
          "id": 1,
          "name": "Finn",
          "age": 15,
          "has_magic": false,
          "modified_at":"2020-01-13T21:25:03+0000"
        }
      }
    ],
    "key_names": [
      "id"
    ]
  }'
Pushing multiple records
curl -X "POST" "https://api.stitchdata.com/v2/import/batch" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'{
   "table_name":"customers",
   "schema":{
      "properties":{
         "id":{
            "type":"integer"
         },
         "name":{
            "type":"string"
         },
         "age":{
            "type":"integer"
         },
         "has_magic":{
            "type":"boolean"
         },
         "modified_at":{
            "type":"string",
            "format":"date-time"
         }
      }
   },
   "messages":[
      {
         "action":"upsert",
         "sequence":1565881320,
         "data":{
            "id":2,
            "name":"Jake",
            "age":6,
            "has_magic":true,
            "modified_at":"2020-01-13T21:25:03+0000"
         }
      },
      {
         "action":"upsert",
         "sequence":1565838645,
         "data":{
            "id":3,
            "name":"Bubblegum",
            "age":17,
            "has_magic":true,
            "modified_at":"2020-01-14T13:34:25+0000"
         }
      }
   ],
   "key_names":[
      "id"
   ]
}'
Pushing a record without a Primary Key
curl -X "POST" "https://api.stitchdata.com/v2/import/batch" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'{
   "table_name":"customers_no_primary_keys",
   "schema":{
      "properties":{
         "name":{
            "type":"string"
         },
         "age":{
            "type":"integer"
         },
         "has_magic":{
            "type":"boolean"
         },
         "modified_at":{
            "type":"string",
            "format":"date-time"
         }
      }
   },
   "messages":[
      {
         "action":"upsert",
         "sequence":1565881320,
         "data":{
            "name":"BMO",
            "age":2,
            "has_magic":false,
            "modified_at":"2020-01-20T05:57:01+0000"
         }
      }
   ]
}'

Responses for POST /v2/import/batch


{
  "status": "OK",
  "message": "Batch Accepted!"
}

{
  "status": "Accepted",
  "message": "The batch is queued to be processed."
}
Code Condition Response body
400

Request body is missing required arguments

{
  "error": "Request failed validation:#: required key [<ARGUMENT_NAME>] not found"
}
400

Request body contains an illegal argument

{
  "error": "Request failed validation:#: extraneous key [<ARGUMENT_NAME>] is not permitted"
}
400

Required argument is incorrectly typed

{
  "error": "Request failed validation:#/<ARGUMENT_NAME>: expected type: <CORRECT_TYPE>, found: <TYPE>"
}
400

Record in Message object doesn’t conform to the Schema

{
  "error": "Record 0 did not conform to schema: #/<FIELD_NAME>: expected: <DATA_TYPE>, found: <DATA_TYPE>"
}
400

key_names are provided, but a record has a missing or null key value

{
  "error": "Record is missing key property <KEY_NAME>"
}
400

Invalid JSON data type in Schema object

{
  "error": "Invalid JSON schema: unknown type: [<TYPE>]"
}
400

Required argument missing from the Message object

{
  "error": "Request failed validation:#/messages/0: #: 0 subschemas matched instead of one #/messages/0: 2 schema violations found #/messages/0: required key [<ARGUMENT_NAME>] not found #/messages/0: extraneous key [data] is not permitted #/messages/0: required key [ARGUMENT_NAME] not found"
}
400

Value of the sequence argument exceeds allowed maximum value

{
  "error": "Request failed validation:#: sequence can not be above 9223372036854775807"
}
400

The Schema object must be an object, not an array

{
  "error": "Request failed validation:#/schema: expected type: JSONObject, found: JSONArray"
}
401

Access token is missing or invalid

{  
   "message":"Not Authorized"
}
401

Integration is paused or has been deleted

{
  "error": "Forbidden",
  "errors": {
    "error": "Connection is not active."
  }
}
413

Request body exceeds {{ site.data.import-api.general.max-record-size }}

{
  "status": "ERROR",
  "message": "Request rejected: request size (<BYTE>s bytes) exceeds the maximum"
}
415

Unsupported content type

Content-Type must be application/json



Validate

An object containing table information, your client ID, and data objects representing records to be validated without being persisted to Stitch. The Validate object is identical to the Push object.

Endpoints

POST Validate a push request

Validates request credentials and batch data, but doesn’t persist the data to Stitch. This allows you to validate your API credentials and batch data during development.


OBJECT

The Validate object

An object containing table information, your client ID, and data objects representing records to be validated without being persisted to Stitch. The Validate object is identical to the Push object.

client_id
INTEGER

The Stitch client ID associated with your Stitch account.

To locate your client ID, sign into your Stitch account and look at the URL. The client ID is the four to six-digit number between client and pipeline in the URL.

For example: If the URL is https://app.stitchdata.com/v2/client/7723/pipeline/connections, the client ID would be 7723.

table_name
STRING

The name of the destination table the data is being pushed to. Table names must be unique in each destination schema, or loading issues will occur.

A single request can push data to multiple tables.

Note: The number of characters in the table name should be within the destination’s allowed limits or data will rejected.

sequence
INTEGER

An integer that tells the Import API the order in which data points in the request body should be considered for loading. This data will be stored in the destination table in the _sdc_sequence column.

In other Stitch integrations, Stitch uses a Unix epoch (in milliseconds) as the value for this property.

Note: This value cannot exceed the maximum of 9223372036854775807.

action
STRING

This will always be upsert.

key_names
ARRAY

An array of strings representing the Primary Key fields in the destination table.

  • All fields defined as Primary Keys must be present in the data object and their value cannot be null
  • If a Primary Key is a string, its value must be less than 256 characters
  • Primary Key fields must be top-level fields in the table. For example: When sending JSON, a Primary Key field cannot be contained in an object or an array.
data
OBJECT

An object representing a record to be pushed into the destination table.

  • All fields included in key_names must be included and their values cannot be null
  • The maximum number of data points per data object is 10,000
  • If a Primary Key is a string, its value must be less than 256 characters

Refer to the Structuring data for the Import API guide for instructions and examples.

Example object
{
  "client_id":7723,
  "table_name":"customers",
  "sequence":1565880017,
  "data":{
     "id":1,
     "name":"Finn"
  },
  "key_names":[
     "id"
  ],
  "action":"upsert"
}

POST

Validate a push request

Note: With the exception of not persisting data, this endpoint is functionally identical to the Push endpoint. The Validate endpoint will not work if a request body intended for the Batch endpoint is sent.

Validates request credentials and batch data, but doesn’t persist the data to Stitch. This allows you to validate your API credentials and batch data during development.

Regardless of whether the Import API is functional, this endpoint will never return a 503 Service Unavailable response. Use the Status endpoint to determine if the Import API is experiencing issues.

Resource list
Request Method

POST

Resource URL

/v2/import/validate

Authorization

Required. The request header must contain Authorization and your Import API access token.

Request Header

The request header must contain the following:

  • Authorization: Must specify Bearer Auth, e.g. Bearer: <ACCESS_TOKEN>

  • Content-Type: Must specify JSON, e.g. application/json

See the Request tab below for example requests.

Request Body

The request body must be valid JSON or Transit and contain the required arguments.

The request body should provide an array (batch) of records to be inserted into the pipeline that comply with the following:

  • Must contain all required arguments.

  • Cannot exceed {{ site.data.import-api.general.max-record-size }} in size.

  • Each data object in the request body must contain between 1 and 20,000 records.

  • Each data object in the request body cannot exceed 10,000 individual data points.

  • Must contain a valid client_id. Each record in the request body must have the same client_id.

  • Must be an array (batch) of records. The root cannot be an object.

Response Format

Whether the request succeeds or fails, the API will return JSON.

Errors

See the Errors tab, below.

Arguments

This endpoint accepts the following parameters:

client_id
INTEGER
REQUIRED

The Stitch client ID associated with your Stitch account.

To locate your client ID, sign into your Stitch account and look at the URL. The client ID is the four to six-digit number between client and pipeline in the URL.

For example: If the URL is https://app.stitchdata.com/v2/client/7723/pipeline/connections, the client ID would be 7723.

Note: This must be the same for every record in the request body.

table_name
STRING
REQUIRED

The name of the destination table the data is being pushed to. Table names must be unique in each destination schema, or loading issues will occur.

A single request can push data to multiple tables.

Note: The number of characters in the table name should be within the destination’s allowed limits or data will rejected.

sequence
INTEGER
REQUIRED

An integer that tells the Import API the order in which data points in the request body should be considered for loading. This data will be stored in the destination table in the _sdc_sequence column.

In other Stitch integrations, Stitch uses a Unix epoch (in milliseconds) as the value for this property.

Note: This value cannot exceed the maximum of 9223372036854775807.

action
STRING
REQUIRED

This will always be upsert.

key_names
ARRAY
REQUIRED

An array of strings representing the Primary Key fields in the destination table.

  • All fields defined as Primary Keys must be present in the data object and their value cannot be null
  • If a Primary Key is a string, its value must be less than 256 characters
  • Primary Key fields must be top-level fields in the table. For example: When sending JSON, a Primary Key field cannot be contained in an object or an array.
data
OBJECT
REQUIRED

An object representing a record to be pushed into the destination table.

  • All fields included in key_names must be included and their values cannot be null
  • The maximum number of data points per data object is 10,000
  • If a Primary Key is a string, its value must be less than 256 characters

Refer to the Structuring data for the Import API guide for instructions and examples.

Returns

If successful, the API will return a 200 OK status and a Batch Status object.

POST /v2/import/validate
curl -X "POST" "https://api.stitchdata.com/v2/import/validate" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'[
   {
      "client_id":7723,
      "table_name":"customers",
      "sequence":1565881320,
      "key_names":[
         "id"
      ],
      "data":{
         "id":1,
         "name":"Finn"
      },
      "action":"upsert"
   }
]'
Response for POST /v2/import/validate
{
  "status": "OK",
  "message": "Batch is valid!"
}
Code Condition Response body
400

Request body is not an array

{
  "status": "ERROR",
  "message": "An array of records is expected"
}
400

Request body is malformed

{
  "status": "ERROR",
  "message": "Malformed json in the body!",
  "error": "Unexpected character (']' (code 93)): expected a value\n at [Source: java.io.StringReader@796a657e; line: 16, column: 2]",
  "input": null
}
401

client_id missing from request body

{
  "status": "ERROR",
  "error": "Not Authenticated.",
  "errors": null
}
401

Integration is paused or has been deleted

{
  "error": "Forbidden",
  "errors": {
    "error": "Connection is not active."
  }
}
403

client_id and access token mismatch

{
  "status": "ERROR",
  "error": "Forbidden",
  "errors": {
    "error": "Access token is not associated with this client."
  }
}
405

Unsupported method

Method not allowed.

413

Request body exceeds {{ site.data.import-api.general.max-record-size }}

{
  "status": "ERROR",
  "message": "Request rejected: request size (<BYTE>s bytes) exceeds the maximum"
}
415

Unsupported content type

{
  "status": "ERROR",
  "message": "Unsupported content-type application/<TYPE>. Please send application/json or application/transit+json"
}
422

Multiple client IDs in request

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": "The batch contains data points for multiple clients. Only client_id <CLIENT_ID> is allowed"
    }
  ]
}
422

Required argument is missing or blank

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "<REQUIRED_ARGUMENT_NAME>": {
        "table_name": [
          "can't be blank"
        ]
      }
    }
  ]
}
422

Required argument is incorrectly typed

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "sequence": [
          "should be an integer",
          "should be a number"
        ]
      }
    }
  ]
}
422

data must be typed as an object

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "data must be an object"
        ]
      }
    }
  ]
}
422

data must include fields in key_names

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "data must include keys"
        ]
      }
    }
  ]
}
422

Key values in data cannot be null

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "keys cannot not be null in data"
        ]
      }
    }
  ]
}
422

Key names not provided

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "key_names": [
          "can't be blank"
        ],
        "key_properties": [
          "unknown key"
        ]
      }
    }
  ]
}
422

String values in key fields cannot exceed 1,024 characters

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "String keys cannot be longer than 1024 characters"
        ]
      }
    }
  ]
}


Push

An object containing table information, your client ID, and data objects representing records to be pushed to Stitch.

Endpoints

POST Push data

Pushes data for a specified table or tables to Stitch.


OBJECT

The Push object

An object containing table information, your client ID, and data objects representing records to be pushed to Stitch.

client_id
INTEGER

The Stitch client ID associated with your Stitch account.

To locate your client ID, sign into your Stitch account and look at the URL. The client ID is the four to six-digit number between client and pipeline in the URL.

For example: If the URL is https://app.stitchdata.com/v2/client/7723/pipeline/connections, the client ID would be 7723.

table_name
STRING

The name of the destination table the data is being pushed to. Table names must be unique in each destination schema, or loading issues will occur.

A single request can push data to multiple tables.

Note: The number of characters in the table name should be within the destination’s allowed limits or data will rejected.

sequence
INTEGER

An integer that tells the Import API the order in which data points in the request body should be considered for loading. This data will be stored in the destination table in the _sdc_sequence column.

In other Stitch integrations, Stitch uses a Unix epoch (in milliseconds) as the value for this property.

Note: This value cannot exceed the maximum of 9223372036854775807.

action
STRING

This will always be upsert.

key_names
ARRAY

An array of strings representing the Primary Key fields in the destination table.

  • All fields defined as Primary Keys must be present in the data object and their value cannot be null
  • If a Primary Key is a string, its value must be less than 256 characters
  • Primary Key fields must be top-level fields in the table. For example: When sending JSON, a Primary Key field cannot be contained in an object or an array.
data
OBJECT

An object representing a record to be pushed into the destination table.

  • All fields included in key_names must be included and their values cannot be null
  • The maximum number of data points per data object is 10,000
  • If a Primary Key is a string, its value must be less than 256 characters

Refer to the Structuring data for the Import API guide for instructions and examples.

Example object
{
  "client_id":7723,
  "table_name":"customers",
  "sequence":1565880017,
  "data":{
     "id":1,
     "name":"Finn"
  },
  "key_names":[
     "id"
  ],
  "action":"upsert"
}

POST

Push data

Pushes data for a specified table or tables to Stitch.

When data for a table is pushed for the first time, Stitch will create the table in the destination in the specified integration schema.

During subsequent pushes, one of two things will happen depending on the destination being used:

  1. If the destination supports upserts, Stitch will perform an update operation on applicable existing rows to overwrite the data.
  2. If the destination doesn’t support upserts, Stitch will load the records in an append-only fashion. This means that existing records in the destination table will not be updated, and all records in subsequent pushes will be appended to the end of the table.

Structuring request body data

Refer to the Structuring data for the Import API guide for instructions and examples.

Resource list
Request Method

POST

Resource URL

/v2/import/push

Authorization

Required. The request header must contain Authorization and your Import API access token.

Request Header

The request header must contain the following:

  • Authorization: Must specify Bearer Auth, e.g. Bearer: <ACCESS_TOKEN>

  • Content-Type: Must specify one of the following:

    • application/json - If using JSON
    • application/transit+json - If using Transit

See the Request tab below for example requests.

Request Body

The request body must be valid JSON or Transit and contain the required arguments.

Additionally, the request body should provide an array (batch) of records to be inserted into the pipeline that adhere to the following:

  • Must contain all required arguments.

  • Cannot exceed 20MB in size.

  • Each data object in the request body must contain between 1 and 20,000 records.

  • Each data object in the request body cannot exceed 10,000 individual data points.

  • Must contain a valid client_id. Each record in the request body must have the same client_id.

  • Must be an array (batch) of records. The root cannot be an object.

Response Format

Whether the request succeeds or fails, the API will return JSON.

Errors

See the Errors tab, below.

Arguments

This endpoint accepts the following parameters:

client_id
INTEGER
REQUIRED

The Stitch client ID associated with your Stitch account.

To locate your client ID, sign into your Stitch account and look at the URL. The client ID is the four to six-digit number between client and pipeline in the URL.

For example: If the URL is https://app.stitchdata.com/v2/client/7723/pipeline/connections, the client ID would be 7723.

Note: This must be the same for every record in the request body.

table_name
STRING
REQUIRED

The name of the destination table the data is being pushed to. Table names must be unique in each destination schema, or loading issues will occur.

A single request can push data to multiple tables.

Note: The number of characters in the table name should be within the destination’s allowed limits or data will rejected.

sequence
INTEGER
REQUIRED

An integer that tells the Import API the order in which data points in the request body should be considered for loading. This data will be stored in the destination table in the _sdc_sequence column.

In other Stitch integrations, Stitch uses a Unix epoch (in milliseconds) as the value for this property.

Note: This value cannot exceed the maximum of 9223372036854775807.

action
STRING
REQUIRED

This will always be upsert.

key_names
ARRAY
REQUIRED

An array of strings representing the Primary Key fields in the destination table.

  • All fields defined as Primary Keys must be present in the data object and their value cannot be null
  • If a Primary Key is a string, its value must be less than 256 characters
  • Primary Key fields must be top-level fields in the table. For example: When sending JSON, a Primary Key field cannot be contained in an object or an array.
data
OBJECT
REQUIRED

An object representing a record to be pushed into the destination table.

  • All fields included in key_names must be included and their values cannot be null
  • The maximum number of data points per data object is 10,000
  • If a Primary Key is a string, its value must be less than 256 characters

Refer to the Structuring data for the Import API guide for instructions and examples.

Returns

If successful, the API will return a 2xx status and a Batch Status object:

  • 201 - The request was accepted and will be processed later. New data will be added once the request is processed.

  • 202 - The request was accepted, but cannot currently be processed due to an internal error. Data will be automatically re-processed.

Requests for POST /v2/import/push

Pushing a single record for a single table
curl -X "POST" "https://api.stitchdata.com/v2/import/push" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'[
   {
      "client_id":7723,
      "table_name":"customers",
      "sequence":1565880017,
      "data":{
         "id":1,
         "name":"Finn"
      },
      "key_names":[
         "id"
      ],
      "action":"upsert"
   }
]'
Pushing multiple records for a single table
curl -X "POST" "https://api.stitchdata.com/v2/import/push" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'[
   {
      "client_id":7723,
      "table_name":"customers",
      "sequence":1565880017,
      "data":{
         "id":4,
         "name":"BMO"
      },
      "key_names":[
         "id"
      ],
      "action":"upsert"
   },
   {
      "client_id":7723,
      "table_name":"customers",
      "sequence":1565838645,
      "data":{
         "id":5,
         "name":"Ice King"
      },
      "key_names":[
         "id"
      ],
      "action":"upsert"
   }
]'
Pushing records for multiple tables
curl -X "POST" "https://api.stitchdata.com/v2/import/push" \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d $
'[
   {
      "client_id":7723,
      "table_name":"customers",
      "sequence":1565880017,
      "data":{
         "id":4,
         "name":"BMO"
      },
      "key_names":[
         "id"
      ],
      "action":"upsert"
   },
   {
      "client_id":7723,
      "table_name":"orders",
      "sequence":1565838645,
      "data":{
         "order_id":561,
         "customer_id":4
      },
      "key_names":[
         "order_id"
      ],
      "action":"upsert"
   }
]'

Responses for POST /v2/import/push


{
  "status": "OK",
  "message": "Batch Accepted!"
}

{
  "status": "Accepted",
  "message": "The batch is queued to be processed."
}
Code Condition Response body
400

Request body is not an array

{
  "status": "ERROR",
  "message": "An array of records is expected"
}
400

Request body is malformed

{
  "status": "ERROR",
  "message": "Malformed json in the body!",
  "error": "Unexpected character (']' (code 93)): expected a value\n at [Source: java.io.StringReader@796a657e; line: 16, column: 2]",
  "input": null
}
401

client_id missing from request body

{
  "status": "ERROR",
  "error": "Not Authenticated.",
  "errors": null
}
401

Integration is paused or has been deleted

{
  "error": "Forbidden",
  "errors": {
    "error": "Connection is not active."
  }
}
403

client_id and access token mismatch

{
  "status": "ERROR",
  "error": "Forbidden",
  "errors": {
    "error": "Access token is not associated with this client."
  }
}
405

Unsupported method

Method not allowed.

413

Request body exceeds {{ site.data.import-api.general.max-record-size }}

{
  "status": "ERROR",
  "message": "Request rejected: request size (<BYTE>s bytes) exceeds the maximum"
}
415

Unsupported content type

{
  "status": "ERROR",
  "message": "Unsupported content-type application/<TYPE>. Please send application/json or application/transit+json"
}
422

Multiple client IDs in request

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": "The batch contains data points for multiple clients. Only client_id <CLIENT_ID> is allowed"
    }
  ]
}
422

Required argument is missing or blank

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "<REQUIRED_ARGUMENT_NAME>": {
        "table_name": [
          "can't be blank"
        ]
      }
    }
  ]
}
422

Required argument is incorrectly typed

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "sequence": [
          "should be an integer",
          "should be a number"
        ]
      }
    }
  ]
}
422

data must be typed as an object

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "data must be an object"
        ]
      }
    }
  ]
}
422

data must include fields in key_names

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "data must include keys"
        ]
      }
    }
  ]
}
422

Key values in data cannot be null

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "keys cannot not be null in data"
        ]
      }
    }
  ]
}
422

Key names not provided

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "key_names": [
          "can't be blank"
        ],
        "key_properties": [
          "unknown key"
        ]
      }
    }
  ]
}
422

String values in key fields cannot exceed 1,024 characters

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "String keys cannot be longer than 1024 characters"
        ]
      }
    }
  ]
}

Data Structures

OBJECT Batch Status

A Batch Status object provides information about the validation and acceptance status of a batch of data in a request body. Note: This object is only returned if the request body complies with the endpoint’s requirements.

OBJECT Error

An Error object provides information about the reason a request resulted in an error response from the Import API.

OBJECT Error Reason

Contained in an Error object, the Error Reason object contains additional details about the reason a request resulted in an error response.

OBJECT Message

A Message object contains information about a record to be upserted into a table.

OBJECT Schema

A Schema object contains a valid JSON schema describing the record(s) in a Message object’s data property.

Refer to the JSON schema docs for more info about JSON schemas.


OBJECT

The Batch Status object

A Batch Status object provides information about the validation and acceptance status of a batch of data in a request body. Note: This object is only returned if the request body complies with the endpoint’s requirements.

status
STRING

The batch status. Possible values are:

  • OK - Corresponds to a 201 Created response code if using the Push endpoint, or a 200 OK response code if using the Validate endpoint
  • Accepted - Corresponds to a 202 Accepted response code
message
STRING

A message describing the current status of the batch.

Example object

{
  "status": "OK",
  "message": "Batch is valid!"
}
{
  "status": "OK",
  "message": "Batch Accepted!"
}
{
  "status": "Accepted",
  "message": "The batch is queued to be processed."
}

OBJECT

The Error Reason object

Contained in an Error object, the Error Reason object contains additional details about the reason a request resulted in an error response.

reason
STRING, OBJECT

A string or an object describing the reason for the error.

When an object, the structure of this object is "[field_name]": ["error_reason"], where field_name is the name of the argument that caused the error, and error_reason is an array of strings describing the reason for the error.

For example: "data": ["data must include keys"]

Example object

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": "The batch contains data points for multiple clients. Only client_id <CLIENT_ID> is allowed"
    }
  ]
}
{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "data must include keys"
        ]
      }
    }
  ]
}

OBJECT

The Error object

An Error object provides information about the reason a request resulted in an error response from the Import API.

status
STRING

This will always be ERROR.

message
STRING

A message describing the error.

error
STRING

The reason for the error.

errors
ARRAY (ERROR REASON)

An array of error reason objects that describe the properties causing the error.

Example object

{
  "status": "ERROR",
  "error": "Request cannot be processed; see errors.",
  "errors": [
    {
      "reason": {
        "data": [
          "data must include keys"
        ]
      }
    }
  ]
}
{
  "status": "ERROR",
  "message": "An array of records is expected"
}

OBJECT

The Message object

A Message object contains information about a record to be upserted into a table.

action
STRING

This will always be upsert.

sequence
INTEGER

An integer that tells the Import API the order in which data points in the request body should be considered for loading. This data will be stored in the destination table in the _sdc_sequence column.

In other Stitch integrations, Stitch uses a Unix epoch (in milliseconds) as the value for this property.

Note: This value cannot exceed the maximum of 9223372036854775807.

data
OBJECT

The record to be upserted into a table. The record data must conform to the JSON schema contained in the request’s Schema object.

Example object

{
  "action": "upsert",
  "sequence": 1574796577000,
  "data": {
    "id": 1,
    "name": "Finn",
    "age": 16,
    "has_magic": false
  }
}

OBJECT

The Schema object

A Schema object contains a valid JSON schema describing the record(s) in a Message object’s data property.

Refer to the JSON schema docs for more info about JSON schemas.

properties
OBJECT

The JSON schema that records in the data property must conform to.

Example object

{
   "schema":{
      "properties":{
         "id":{
            "type":"integer"
         },
         "name":{
            "type":"string"
         },
         "age":{
            "type":"number"
         },
         "has_magic":{
            "type":"boolean"
         }
      }
   }
}