Connect to the SEEN API

Authorization

All requests to our API must be authenticated. In order to authenticate, please include the following header in your requests:

Name: Authorization Value: Token {auth_token}

auth_token: We will generate an authentication token for you.

Create a new Receiver

Endpoint

POST: https://api.seen.io/v1/campaigns/{campaign_slug}/receivers/

campaign_slug: You will be given a alphanumeric campaign id, e.g. “welcome-film” for each new campaign/project.

Request Headers

Authorization: This header is common to all requests to our API. Please see the “Authorization” section.

Content-Type: We recommend that you set this to: application/json; charset=utf-8

Request Content

Here is an example of a payload. Fields can differ depending on setup.

Each request payload should be an array of JSON objects, this allows for the creating of multiple receivers at once. Fields are as follows:

customer_id - Alphanumeric ID that will be stored in our database and sent back to you during callbacks. This is useful for matching each receiver between our database and yours. (string)

first_name (required) - First name(s) of the new receiver. (string)

last_name - The receiver’s last name(s), if any. (string)

email - Email address to deliver the generated emails to, if enabled for the campaign. (string)

phone - Phone number to deliver the generated SMS messages to, if enabled for the campaign. The phone number must be in the E.164 format, e.g. “+4712345678”. (string)

extra_args - This object contains any other fields necessary to generate the films, e.g. gender, address, number of miles travelled. These data points will generally be used in the final film. The format of this object will need to be agreed upon between SEEN and the client, and will contain relevant personalisations. (JSON object).

[
    {
        "first_name": "John",
        "last_name": "Rowley",
        "email": "john.rowley@seen.io",
        "phone": "+4745860321",
        "customer_id": "100",
        "extra_args": {
            "gender": "male",
             "city": "Oslo"
        }
    },
    {
        "first_name": "Jane",
        "last_name": "Rowley",
        "email": "jane.rowley@seen.io",
        "customer_id": "101",
        "extra_args": {
            "gender": "female",
             "city": "Oslo"
        }
    }
]

Accepted characters in field names: Alphanumeric characters (A-Z, 0-9), as well as underscore (_). For example, use "o" instead of "ø".

Please note that if SEEN is to send out the generated movies ourselves, you must supply a valid phone number, email address, or both, otherwise we will have no means of delivery.

If callbacks are enabled for the campaign, it's recommended to supply a unique id (customer_id) that can be used to match each receiver between our respective systems.

Images via URL

To be able to send images via URL in an API call, this is the requirements:

Image size limit is 2 MB.

Only use images with file extension .jpg .jpeg or .png (only lowercase extension is allowed).

The image should provide a content type. image/jpg, image/jpeg or image/png.

Only use direct links that do not require authentication to the images. Do not use redirect links.

Here is an example of an image via URL:

https://video.storm121.com/seen-example-films/images/Seen.png

Responses

Upon posting the request, you will receive one of the following responses from our API:

201 Created

The receiver(s) were created and we will generate and send the videos on a schedule agreed to beforehand.

400 Bad Request

field_name - The name of the field that has failed validation.

error_message - A user-friendly error message that will explain why the validation failed.

[
    {
        "{field_name}": [
            "{error_message}"
        ]
    }
]

If the data you send us fails validation, you will receive an array of JSON objects.

Each JSON object will contain the name of the field that has failed validation as its key, and an array of error message strings as its value.

For example, if you do try to create a receiver with an id that already exists, you will receive the following JSON response:

[
    {
        "customer_id": [
            "A receiver with this ID already exists."
        ]
    }
]

Error responses are sent in order, e.g. if you send 3 receivers, but the second receiver has errors, the second JSON object will contain the errors that need to be fixed:

[
    {},
    {
        "customer_id": [
            "A receiver with this ID already exists."
        ]
    },
    {}

Overview