NAV Navbar
shell

Inkit Public API

Welcome to the Inkit Public API! Get familiar with Inkit documentation and explore our API.

Authentication

A token needs to be sent with the Authorization header. To successfully authenticate, send the token header below with your request.

Key Value
Authorization Inkit {api-key}
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Inkit {api-key}"

Make sure to replace {api-key} with your API key.

Rate Limit

Rate limits may be included in future releases of our public API. For version 1.0.0, there is currently no rate limit.

Contacts

GET /v1/contacts/

curl -X GET --header "Accept: application/json" --header "Authorization: Inkit <api-key>" "http://api.next.inkit.io/v1/contacts/"

The above command returns JSON structured like this:

[
  {
    "body": {
      "id": "string",
      "created_at": "2019-02-16T19:01:53.700Z",
      "updated_at": "2019-02-16T19:01:53.700Z",
      "source": "string",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "address": {
        "street": "string",
        "unit": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      },
      "email": "string",
      "tags": [
        "string"
      ],
      "custom_data": {}
    },
    "response": {
      "message": "string",
      "status_code": 200
    }
  }
]

Summary: Returns contact list data based on your user id.

GET /v1/contacts/ or GET /v1/contacts/{contact_id}

Retrieves list of contacts, or single contact by contact_id.

Contact Schema

Field Type Description
id uuid The unique id for the contact.
created_at timestamp When the contact was first created.
updated_at timestamp When the contact was last updated.
source string The source from where the contact was created.
first_name string The first name of the contact.
last_name string The last name of the contact. (optional)
company string The company name that contact belongs to (optional)
email string The email address for contact. (optional)
address object See address schema below
tags list List of related tags ids (optional)
custom_data map A map of arbitrary string keys to arbitrary scalar values.

POST /v1/contacts/

curl -X POST -d ```
{
    "first_name": "Jessica",
    "last_name": "Alba",
    "company": "Actress Company LLC",
    "email": "j.alba@gmail.com",
    "address": {
        "street": "222 Fake Ln",
        "unit": "St 42",
        "city": "San Diego",
        "state": "CA",
        "zip": "90210",
        "country": "US"
    }
    "tags": ["december-campaign"],
    "custom_data": {
        "custom_field_a": "custom data",
        "new_custom_field": "new data"
        }
}
``` --header "Accept: application/json" --header "Authorization: Inkit <api-key>" "http://api.next.inkit.io/v1/contacts/"

The above command returns JSON structured like this:

{
    "first_name": "Jessica",
    "last_name": "Alba",
    "company": "Actress Company LLC",
    "email": "j.alba@gmail.com",
    "address": {
        "street": "111 Fake Ln",
        "unit": "St 42",
        "city": "San Diego",
        "state": "CA",
        "zip": "90210",
        "country": "US"
    },
    "tags": ["december-campaign"],
    "custom_data": {
        "custom_field_a": "custom data"
        }
}

Creates a new contact from the request body. The request fields map to the database field names.

A few edge cases should be handled here:

Request Data

All requests should have their POST data should be stored in the request body.

Contact Schema

Field Type Description
first_name string The first name of the contact.
last_name string The last name of the contact. (optional)
company string The company name that contact belongs to (optional)
email string The email address for contact. (optional)
address object See address schema below
tags list List of related tags ids (optional)
custom_data map A map of arbitrary string keys to arbitrary scalar values.

Address Schema

Field Type Description
street string The primary line, or street address of the contact (64-character limit)
unit string The apartment or suite number. (optional)
city string The city for the contact"s address
state string The two-letter (2) state code.
zip string The zipcode of the contact"s address
country string The two-letter (2) country code.

PATCH /v1/contacts/{contact_id}

Updates contact information for specific contact_id. The updated_at field is updated to the timestamp where the contact was updated.

curl -X PATCH -d
{
    "first_name": "Jessica",
    "last_name": "Alba",
    "company": "Actress Company LLC",
    "email": "j.alba@gmail.com",
    "address": {
        "street": "222 Fake Ln",
        "unit": "St 42",
        "city": "San Diego",
        "state": "CA",
        "zip": "90210",
        "country": "US"
    }
    "tags": ["december-campaign"],
    "custom_data": {
        "custom_field_a": "custom data",
        "new_custom_field": "new data"
        }
} --header "Accept: application/json" --header "Authorization: <api-key>" "http://api.next.inkit.io/v1/contacts/"

The above command returns JSON structured like this:

{
    "data": {
        "id": "af02d300029182fbe2b3a6ead66c33f0",
        "created_at": "2018-11-08T14:31",
        "updated_at": "2018-12-09T09:22",
        "source": "api",
        "first_name": "Jessica",
        "last_name": "Alba",
        "company": "Actress Company LLC",
        "email": "j.alba@gmail.com",
        "address": {
            "street": "222 Fake Ln",
            "unit": "St 42",
            "city": "San Diego",
            "state": "CA",
            "zip": "90210",
            "country": "US"
        }
        "tags": "december-campaign",
        "custom_data": {
            "custom_field_a": "custom data",
            "new_custome_field": "new data"
            }
        },
    "response": {
        "message": "",
        "status_code": 200
    }
}

Contact Schema

Field Type Description
first_name string The first name of the contact.
last_name string The last name of the contact. (optional)
company string The company name that contact belongs to (optional)
email string The email address for contact. (optional)
address object See address schema below
tags list List of related tags ids (optional)
custom_data map A map of arbitrary string keys to arbitrary scalar values.

Address Schema

Field Type Description
street string The primary line, or street address of the contact (64-character limit)
unit string The apartment or suite number. (optional)
city string The city for the contact"s address
state string The two-letter (2) state code.
zip string The zipcode of the contact"s address
country string The two-letter (2) country code.

DELETE /v1/contacts/{contact_id}

Removes all tags from contact and sets the deleted_at date.

curl -X DELETE -d --header "Accept: application/json" --header "Authorization: Inkit <api-key>" "http://api.next.inkit.io/v1/contacts/{contact_id}"
{
    "response": {
        "message": "Successfully Deleted",
        "status_code": 204
    }
}

Tags

GET /v1/tags/ or GET /v1/tags/{tag_id}

The /tags/ endpoint retrieves all tags that are associated with the contacts for your account. Tags are used to categorize contacts into groups. Currently you may only send campaigns to tagged contacts through our application.

curl -X GET --header "Accept: application/json" --header "Authorization: Inkit <api-key>" "http://api.next.inkit.io/v1/tags/"

The above command returns JSON structured like this:

{
    "data": [{
        "id": "9b5c6503f189453cb006778e66416263",
        "created_at": "2018-11-19T12:01",
        "updated_at": "2018-11-19T12:01",
        "name": "december-campaign"
        },
        {
        "id": "d70f5ac2a4e30bdc11f75e8d85709657",
        "created_at": "2018-11-21T11:31",
        "updated_at": "2018-11-21T11:31",
        "name": "january-campaign"
        }],
    "response": {
        "message": "",
        "status_code": 200
    }
}
Field Type Description
id string The identifier of the tag.
created_at timestamp The timestamp when the tag was created.
updated_at timestamp The timestamp when the tag was last updated.
name string The name of the tag.

POST /v1/tags/

curl -X POST -d {
    "name": "december-campaign"
}
--header "Accept: application/json" --header "Authorization: Inkit <api-key>" "http://api.next.inkit.io/v1/tags/"

The above command returns JSON structured like this:

{
    "data": {
        "id": "9b5c6503f189453cb006778e66416263",
        "created_at": "2018-11-19T12:01",
        "updated_at": "2018-11-19T12:01",
        "name": "december-campaign"
        },
    "response": {
        "message": "Successfully Created",
        "status_code": 201
    }
}
Field Type Description
name string The name of the tag

DELETE /v1/tags/{tag_id}

Marks the deleted_at field to a value indicating the tag has been deleted for specific tag_id. Note that when tags are deleted, it removes this tag from all associated contacts.

curl -X DELETE --header "Authorization: Inkit <api-key>" "http://api.next.inkit.io/v1/tags/{tag_id}"

Templates

GET /v1/templates/

curl -X GET --header "Accept: application/json" --header "Authorization: Inkit <api-key>" "http://api.next.inkit.io/v1/templates/"

The above command returns JSON structured like this:

{
    "data": {
        "id": "02bc92c7fa1e6c00e7920e8321492664",
        "created_at": "2018-10-19T12:01",
        "updated_at": "2018-10-19T12:01",
        "created_by_id": "419eb138d2445c57f795b42ab11b7a2a",
        "version": 1,
        "orientation": "landscape",
        "type": "postcard-4x6",
        "name": "December Mailer"
        },
    "response": {
        "message": "",
        "status_code": 201
    }
}

Retrieves templates data

template_id endpoint retrieves just a single template.

Template Schema

Field Type Description
id uuid Unique identifier for template object.
created_at timestamp When the template was created.
updated_at timestamp When the template was updated.
created_by_id uuid Which user created the template.
version integer The media version of the template.
orientation string The orientation of the template (landscape, portrait)
type string The type of template (i.e. "postcard-4x6")
name string The name of the template.

Errors

Inkit Public API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
403 Not Authenticated - Your request hasn't been properly authenticated.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.