NAV Navbar
shell

Introduction

Welcome to the OnboardFlow API.

We have language examples in Shell (with other platform examples coming soon)! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Getting Started

Authentication

OnboardFlow uses API Keys to allow access to the API. You can find your API Key on the API Settings page, when logged into your OnboardFlow account.

The API Key needs to be included in ALL API requests to the server in a header that looks like the following:

Authorization: Bearer e3c0c748fe9b55386eecc07c339ec4099a8b9b0e

Rate Limits

API calls are rate limited to ensure that we are able to provide a consistent quality of service and availability to all of our users. The limits on total calls are illustrated below:

Error Codes

The OnboardFlow API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified record or endpoint 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.
429 Too Many Requests -- You're requesting too many records! Slow down!
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.

Customers

Creating a Customer

curl "https://gateway.onboardflow.com/api/v1/customer/"
  -X POST
  -d '{"site_key":"f37F2PPh","event_date":1583020800,"user_id":"user_123XYZ","customer_id":"cus_123XYZ","customer_first_name":"Joe","customer_has_payment_method":true,"customer_email":"test@onboardflow.com"}'
  -H "Content-Type: application/json"
  -H "Authorization: Bearer e3c0c748fe9b55386eecc07c339ec4099a8b9b0e"

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "id": 979924,
        "event_provider": "API",
        "site_user": {},
        "site_hash": "f37F2PPh",
        "session_id": "f37F2PPh-1585922303",
        "event_date": 1583020800000,
        "event_value": "1923c497cf0fc93ff63414795ec58c59d4ccab38",
        "event_type": "PROVIDER_EVENT",
        "event_meta": {
            "data": {
                "customer": {
                    "id": "cus_123XYZ",
                    "email": "test@onboardflow.com",
                    "user_id": "user_123XYZ",
                    "image_url": null,
                    "last_name": null,
                    "first_name": "Joe",
                    "has_payment_method": true
                },
                "custom_properties": {
                    "qty_tasks": 2,
                    "has_created_project": true
                }
            },
            "type": "CUSTOMER_CREATED",
            "created": 1583020800
        },
        "updated": 1585918703000,
        "created": 1585918703000
    }
}

This method should be called when a new customer is created (typically at the point at which they start a trial).

HTTP Request

POST https://gateway.onboardflow.com/api/v1/customer/

Data Parameters

Parameter Description Type Required
site_key The unique site key of the OnboardFlow site String Yes
event_date The date the customer was created DateTime (Unix Timestamp) Yes
user_id The unique ID of the user this customer record belongs to (typically this will be the ID of your internal user record) String Yes
customer_id The unique ID of the customer being created (if you use a Payment Platform like Stripe this must be the exact same customer ID stored there) String Yes
customer_email The email address of the customer being created String Yes
customer_first_name The first name of the customer being created String No
customer_last_name The last name of the customer being created String No
customer_image_url The absolute URL of the customers profile image (if applicable) String No
customer_has_payment_method A boolean indicating whether this customer has attached a payment method or not Boolean Yes
custom_properties An optional dictionary containing custom properties for this Customer Dict No

Updating a Customer

curl "https://gateway.onboardflow.com/api/v1/customer/"
  -X PUT
  -d '{"site_key":"f37F2PPh","event_date":1583020800,"user_id":"user_123XYZ","customer_id":"cus_123XYZ","customer_first_name":"Joe","customer_has_payment_method":true,"customer_email":"test@onboardflow.com"}'
  -H "Content-Type: application/json"
  -H "Authorization: Bearer e3c0c748fe9b55386eecc07c339ec4099a8b9b0e"

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "id": 979924,
        "event_provider": "API",
        "site_user": {},
        "site_hash": "f37F2PPh",
        "session_id": "f37F2PPh-1585922303",
        "event_date": 1583020800000,
        "event_value": "1923c497cf0fc93ff63414795ec58c59d4ccab38",
        "event_type": "PROVIDER_EVENT",
        "event_meta": {
            "data": {
                "customer": {
                    "id": "cus_123XYZ",
                    "email": "test@onboardflow.com",
                    "user_id": "user_123XYZ",
                    "image_url": null,
                    "last_name": null,
                    "first_name": "Joe",
                    "has_payment_method": true
                },
                "custom_properties": {
                    "qty_tasks": 2,
                    "has_created_project": true
                }
            },
            "type": "CUSTOMER_UPDATED",
            "created": 1583020800
        },
        "updated": 1585918703000,
        "created": 1585918703000
    }
}

This method should be called when a customer has updated their details (such as their name, email address, profile picture URL or when they've added a payment method).

HTTP Request

PUT https://gateway.onboardflow.com/api/v1/customer/

Data Parameters

Parameter Description Type Required
site_key The unique site key of the OnboardFlow site String Yes
event_date The date the customer was updated DateTime (Unix Timestamp) Yes
user_id The unique ID of the user this customer record belongs to (typically this will be the ID of your internal user record) String Yes
customer_id The unique ID of the customer being updated (if you use a Payment Platform like Stripe this must be the exact same customer ID stored there) String Yes
customer_email The email address of the customer being updated String Yes
customer_first_name The first name of the customer being updated String No
customer_last_name The last name of the customer being updated String No
customer_image_url The absolute URL of the customers profile image (if applicable) String No
customer_has_payment_method A boolean indicating whether this customer has attached a payment method or not Boolean Yes
custom_properties An optional dictionary containing custom properties for this Customer Dict No

Deleting a Customer

curl "https://gateway.onboardflow.com/api/v1/customer/"
  -X DELETE
  -d '{"site_key":"f37F2PPh","user_id":"user_123XYZ", "customer_id":"cus_123XYZ"}'
  -H "Content-Type: application/json"
  -H "Authorization: Bearer e3c0c748fe9b55386eecc07c339ec4099a8b9b0e"

HTTP Request

DELETE https://gateway.onboardflow.com/api/v1/customer/

Data Parameters

Parameter Description Type Required
site_key The unique site key of the OnboardFlow site String Yes
user_id The unique ID of the user this customer record belongs to (typically this will be the ID of your internal user record) String Yes
customer_id The unique ID of the customer being created (if you use a Payment Platform like Stripe this must be the exact same customer ID stored there) String Yes

Subscriptions

Creating a Subscription

curl "https://gateway.onboardflow.com/api/v1/subscription/"
  -X POST
  -d '{"site_key":"f37F2PPh","event_date":1583020800,"subscription_name":"Pro","customer_id":"cus_123XYZ","subscription_id":"sub_123XYZ","subscription_value":49.99,"subscription_started_at":1583020800,"subscription_trial_start":1583020800,"subscription_trial_end":1583020800,"subscription_currency":"USD","subscription_status":"active","subscription_interval":"MONTH"}'
  -H "Content-Type: application/json"
  -H "Authorization: Bearer e3c0c748fe9b55386eecc07c339ec4099a8b9b0e"

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "id": 979925,
        "event_provider": "API",
        "site_user": {},
        "session_id": "f37F2PPh-1585922793",
        "event_date": 1583020800000,
        "event_value": "1ec049ab69e84b58d7466816a791a6fd0fe36fa9",
        "event_type": "PROVIDER_EVENT",
        "event_meta": {
            "data": {
                "customer": {
                    "id": "cus_123XYZ"
                },
                "subscription": {
                    "id": "sub_123XYZ",
                    "name": "Pro",
                    "value": 49.99,
                    "status": "active",
                    "currency": "USD",
                    "interval": "MONTH",
                    "trial_end": 1583020800,
                    "product_id": null,
                    "started_at": 1583020800,
                    "trial_start": 1583020800
                }
            },
            "type": "SUBSCRIPTION_CREATED",
            "created": 1583020800
        },
        "updated": 1585919193000,
        "site_hash": "f37F2PPh",
        "created": 1585919193000
    }
}

This method should be called when a customer starts a new subscription (typically at the point at which they start a trial).

HTTP Request

POST https://gateway.onboardflow.com/api/v1/subscription/

Data Parameters

Parameter Description Type Required
site_key The unique site key of the OnboardFlow site String Yes
event_date The date the subscription was created DateTime (Unix Timestamp) Yes
customer_id The unique ID of the customer this subscription is linked to (if you use a Payment Platform like Stripe this must be the exact same customer ID stored there) String Yes
subscription_id The unique ID of the subscription (if you use a Payment Platform like Stripe this must be the exact same subscription ID stored there) String Yes
subscription_name The name of the subscription (usually this is the name of the plan, such as "Pro") String Yes
subscription_status The status of the subscription (possible values are trialing, active and cancelled). String Yes
subscription_interval What is the renewal cycle of this subscription? Possible values are DAY, WEEK, MONTH and YEAR String Yes
subscription_value The value of the subscription (this must take into account any discounts applied - if applicable) Decimal Yes
subscription_currency The currency is this subscription charged in? This must be a valid 3 character ISO 4217 code String Yes
subscription_started_at The date and time that the subscription was created DateTime (Unix Timestamp) Yes
subscription_trial_start The date and time that the trial started (or is due to start) DateTime (Unix Timestamp) Yes
subscription_trial_end The date and time that the trial ended (or is due to end) DateTime (Unix Timestamp) Yes

Updating a Subscription

curl "https://gateway.onboardflow.com/api/v1/subscription/"
  -X PUT
  -d '{"site_key":"f37F2PPh","event_date":1583020800,"subscription_name":"Pro","customer_id":"cus_123XYZ","subscription_id":"sub_123XYZ","subscription_value":49.99,"subscription_started_at":1583020800,"subscription_trial_start":1583020800,"subscription_trial_end":1583020800,"subscription_currency":"USD","subscription_status":"active","subscription_interval":"MONTH"}'
  -H "Content-Type: application/json"
  -H "Authorization: Bearer e3c0c748fe9b55386eecc07c339ec4099a8b9b0e"

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "id": 979925,
        "event_provider": "API",
        "site_user": {},
        "session_id": "f37F2PPh-1585922793",
        "event_date": 1583020800000,
        "event_value": "1ec049ab69e84b58d7466816a791a6fd0fe36fa9",
        "event_type": "PROVIDER_EVENT",
        "event_meta": {
            "data": {
                "customer": {
                    "id": "cus_123XYZ"
                },
                "subscription": {
                    "id": "sub_123XYZ",
                    "name": "Pro",
                    "value": 49.99,
                    "status": "active",
                    "currency": "USD",
                    "interval": "MONTH",
                    "trial_end": 1583020800,
                    "product_id": null,
                    "started_at": 1583020800,
                    "trial_start": 1583020800
                }
            },
            "type": "SUBSCRIPTION_UPDATED",
            "created": 1583020800
        },
        "updated": 1585919193000,
        "site_hash": "f37F2PPh",
        "created": 1585919193000
    }
}

This method should be called when a customer's subscription has changed (for example, this could be when its status changes or if they switch to another plan).

HTTP Request

PUT https://gateway.onboardflow.com/api/v1/subscription/

Data Parameters

Parameter Description Type Required
site_key The unique site key of the OnboardFlow site String Yes
event_date The date the subscription was updated DateTime (Unix Timestamp) Yes
customer_id The unique ID of the customer this subscription is linked to (if you use a Payment Platform like Stripe this must be the exact same customer ID stored there) String Yes
subscription_id The unique ID of the subscription (if you use a Payment Platform like Stripe this must be the exact same subscription ID stored there) String Yes
subscription_name The name of the subscription (usually this is the name of the plan, such as "Pro") String Yes
subscription_status The status of the subscription (possible values are trialing, active and cancelled). String Yes
subscription_interval What is the renewal cycle of this subscription? Possible values are DAY, WEEK, MONTH and YEAR String Yes
subscription_value The value of the subscription (this must take into account any discounts applied - if applicable) Decimal Yes
subscription_currency The currency is this subscription charged in? This must be a valid 3 character ISO 4217 code String Yes
subscription_started_at The date and time that the subscription was created DateTime (Unix Timestamp) Yes
subscription_trial_start The date and time that the trial started (or is due to start) DateTime (Unix Timestamp) Yes
subscription_trial_end The date and time that the trial ended (or is due to end) DateTime (Unix Timestamp) Yes

Events

Logging a UX Event

curl "https://gateway.onboardflow.com/api/v1/tracker/event/"
  -X POST
  -d '{"s":"f37F2PPh","site_user":{"id":"user_123XYZ","customer_id":"cus_123XYZ","custom_properties":{"projects_created":7}},"event":"PAGE_VIEW","value":"/manage/settings/","meta":{"title":"App Settings Page"}}'
  -H "Content-Type: application/json"
  -H "Authorization: Bearer e3c0c748fe9b55386eecc07c339ec4099a8b9b0e"

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "event_date": 1585920768000,
        "event_provider": "JSTRACKER",
        "event_value": "/manage/settings/",
        "id": 979927,
        "site_hash": "f37F2PPh",
        "event_type": "PAGE_VIEW",
        "event_meta": {
            "title": "App Settings Page"
        },
        "site_user": {
            "id": "user_123XYZ",
            "customer_id": "cus_123XYZ",
            "custom_properties": {
                "projects_created": 7
            }
        },
        "created": 1585920768000,
        "updated": 1585920768000
    }
}

Once installed, our JavaScript Tracker will automatically log page views as well as any custom UX events you've setup. However, sometimes it can be useful to log custom UX events via a simple API call. It might also be required to post UX events via the API if you are unable to install the JavaScript Tracker on your app (i.e. if you run a Mobile or Desktop app, rather than a Web app).

HTTP Request

POST https://gateway.onboardflow.com/api/v1/tracker/event/

Data Parameters

Parameter Description Type Required
s The unique site key of the OnboardFlow site String Yes
event The type of UX event you are logging. Possible options are PAGE_VIEW, CLICK or CUSTOM String Yes
event_date The date the UX event took place DateTime (Unix Timestamp) Yes
session_id A unique ID representing the session ID for that user. I.e. you might want to create a new ID each logged in session the user undertakes. String Yes
site_user A dictionary containing details of the user that should be linked to this UX event. At a minimum this should contain an id and customer_id (i.e. {"id": "user_123XYZ", "customer_id":"cus_123XYZ"}). Read more about setting User and Customer ID's here. Dictionary Yes
value If this is a page view event, this should be the URL of the page being viewed. If it's a click it could be the ID of the element or video being watched. No matter what the event is being logged here, this should basically be a value that helps us group similar events in the future (i.e. the URL of the page, ID of the video being watched, class or ID of the button being clicked etc). String Yes
meta If logging a page view or perhaps a video view, then you can set additional properties here about the event. I.e. setting the title would be achieved by setting this to {"title":"App Settings Page"}. Please note that currently, only 'title' is officially supported. Dictionary Yes