Get Started

Overview

The Botdoc API Platform is HTTP-based RESTful API that request and response bodies are formatted in JSON

Important: You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as tokens and IDs with your own values.

Getting Started

Step 1 - Create the Application

When you create an application, Botdoc generates an API Key. Credential for your app for either the sandbox or live environments.
Each application has its own API Key.
DO NOT share it, it's sensitive data.

Step 2 - Authenticate

In exchange for the credentials, the Botdoc authorization server issues access tokens called JWT tokens that you use for authorization when you make REST API requests.

Step 3 - Start making Requests

A JWT token enables you to complete actions on behalf of, and with the approval of, the resource owner and can start making your requests using the endpoints.

Versioning

Why do we have versions?

The goal for having versioning is for developers building apps to be able to understand in advance when the API might change in the future. It helps the developers upgrade their system while the current version is still using a previous version.

Thus, each version will remain for at least from release, therefore giving you a solid timeline for how long your app will remain working, and for how long you have to update it to newer versions.

Versions

Version

Status

Release date

v1

Active

Jan/15/2018

How to set a version?

To set the version you just have to add the version after the domain and before the endpoint.

For example: https://api.botdoc.io/v1/endpoint

If you don't specify the version it will not work!

Sandbox Platform

You shouldn't develop on LIVE environment.
That’s why there is an API Sandbox Platform that is a fully functional environment identical to LIVE which allows you to test it before you go LIVE.

This application must make requests to https://sandboxapi.botdoc.io/{version}

Sandbox and LIVE have the same behavior, however sandbox has a few restrictions:

File size limit: 100mb

Watermark

Mobile text messages (SMS) won't be sent

File storage for only 24 hours

Rate Limits are lower than LIVE

Sandbox and LIVE do NOT share any data.

Going LIVE:

To put your application on LIVE environment you have to go to https://dev.botdoc.io and create a new application. That will be your LIVE application and you have to make requests to https://api.botdoc.io/{version}

Sandbox and LIVE do NOT share any data between them.
You can still keep developing and improving your app on sandbox without having to "switch back" your app to sandbox. It will always be there for you.

Authentication

Botdoc API requires a token to allow access to the API.

Include the JWT token in API requests in the Authorization header with the JWT authentication scheme that looks like the following:

Authorization: JWT {token}

Access tokens have a finite lifetime. The exp field in the access token indicates the expiration date in Unix Timestamp. For example, an expiry value of 1546295415 indicates that the access token expires in 12/31/2018 at 10:30pm (UTC).

To detect when an access token expires:
- Keep track of the exp value in the token response.
- Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.
- Use the verify token endpoint

Important: Cache the access tokens rather than requesting a new token for each API Request. Thus Before you create another token, re-use the access token until it expires.

Query Parameters

For most REST GET calls, you can specify one or more optional query parameters on the request URI to filter, limit the size of, and sort the data in an API response. For filter parameters, see the individual GET calls.

HTTP request headers

The commonly used HTTP request headers are:

Header

Description

Accept

Required for operations with a response body. Specifies the response format to accept JSON. Accept: application/json

Authorization

Required an access token to make API calls. Get your access token then include the JWT Token in the Authorization header with the JWT authentication scheme: Authorization: JWT {token}

Content-Type

Required for operations with a request body. Specifies the request the Content Type format in order to send JSON. Content-Type: application/json

API Responses

Botdoc API calls return HTTP status codes. Some API calls also return JSON response bodies that include data about the resource including one or more contextual HATEOAS links. Use these links to request more information about and construct an API flow that is relative to a specific request.

The request requires authentication and the caller did not provide valid credentials.

403 Forbidden

NOT AUTHORIZED. Authorization failed due to insufficient permissions.

The client is not authorized to access this resource although it might have valid credentials.

404 Not Found

RESOURCE NOT FOUND. The specified resource does not exist.

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database with that id.

405 Method Not Allowed

METHOD NOT SUPPORTED. The server does not implement the requested HTTP method.

The service does not support the requested HTTP method.

415 Unsupported Media Type

UNSUPPORTED MEDIA TYPE. The server does not support the request payload’s media type.

The API cannot process the media type of the request payload. For example, this error occurs if the client sends a Content-Type: application/xml request header but the API can only accept application/json request payloads.

422 Unprocessable Entity

UNPROCESSABLE ENTITY. The API cannot complete the requested action, or the request action is semantically incorrect or fails business validation.

The API cannot complete the requested action and might require interaction with APIs or processes outside of the current request. No systemic problems limit the API from completing the request. For example, this error occurs for any business validation errors, including errors that are not usually of the 400 type.

429 Unprocessable Entity

RATE LIMIT REACHED. Too many requests. Blocked due to rate limiting.

The rate limit for the user, application, or token exceeds a predefined value.

500 Internal Server Error

INTERNAL SERVER ERROR . An internal server error has occurred.

A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.

503 Service Unavailable

SERVICE UNAVAILABLE. Service Unavailable.

The server cannot handle the request for a service due to temporary maintenance.

Requests

This endpoint is in order to either send or request files.

Create Request

Depending on the parameters you can send files to your contacts or request files from them.

There are 2 ways to request/send from/to your contacts:
On the parameters contact you can pass a Contact Object and it will create the request and create the contact automatically. Thus you don't have to create the contact first.
Or you can pass the already existing contact passing the id.

is_draft

short_message

The small message up to 160 characters in order to send the SMS.
The URL to the request comes after the message

long_message_subject

string

optional

The message for the email Subject

long_message_subject

string

optional

The message for the email body

contact

array of contact object

optional

The contact(s) to send the request

callback_url

string

optional

The URL is called when the request gets a response. Botdoc sends a POST with the Request Object

requester

Requester Object

optional

Requester information to be shown on the Request page and Completed page. If you don't pass any requester, the Requester information on the Request page will be the Owner’s profile information and blank on the Completed page of the application.

email_template_slug

string

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

tfa_send_to

enum

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

email In order to the Two Factor Authentication to an email

sms In order to the Two Factor Authentication to a mobile phone via SMS

tfa_send_to_value

string

optional

The value for the tfa_send_to

if the tfa_send_to is email. This value must be an valid email

if the tfa_send_to is sms. This value must be an mobile phone number in E.164 format

requester_privatenotes

type

is_draft

short_message

The small message up to 160 characters in order to send the SMS.
The URL to the request comes after the message

long_message_subject

string

optional

The message for the email Subject

long_message_subject

string

optional

The message for the email body

contact

array of contact object

optional

The contact(s) to send the request

media

array of media object

optional

The media(s) in order to send file(s)

callback_url

string

The URL is called when the request gets a response. Botdoc sends a POST with the Request Object

requester

Requester Object

Requester information to be shown on the Request page and Completed page. If you don't pass any requester, the Requester information on the Request page will be the Owner’s profile information and blank on the Completed page of the application.

email_template_slug

string

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

tfa_send_to

enum

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

email In order to the Two Factor Authentication to an email

sms In order to the Two Factor Authentication to a mobile phone via SMS

tfa_send_to_value

string

optional

The value for the tfa_send_to

if the tfa_send_to is email. This value must be an valid email

if the tfa_send_to is sms. This value must be an mobile phone number in E.164 format

requester_privatenotes

type

is_draft

short_message

The small message up to 160 characters in order to send the SMS.
The URL to the request comes after the message

long_message_subject

string

optional

The message for the email Subject

long_message_subject

string

optional

The message for the email body

contact

array of contact object

optional

The contact(s) to send the request

media

array of media object

optional

The media(s) in order to send file(s)

callback_url

string

The URL is called when the request gets a response. Botdoc sends a POST with the Request Object

requester

Requester Object

Requester information to be shown on the Request page and Completed page. If you don't pass any requester, the Requester information on the Request page will be the Owner’s profile information and blank on the Completed page of the application.

email_template_slug

string

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

tfa_send_to

enum

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

email In order to the Two Factor Authentication to an email

sms In order to the Two Factor Authentication to a mobile phone via SMS

tfa_send_to_value

string

optional

The value for the tfa_send_to

if the tfa_send_to is email. This value must be an valid email

if the tfa_send_to is sms. This value must be an mobile phone number in E.164 format

is_draft

short_message

The small message up to 160 characters in order to send the SMS.
The URL to the request comes after the message

long_message_subject

string

optional

The message for the email Subject

long_message_subject

string

optional

The message for the email body

contact

array of contact object

optional

The contact(s) to send the request

media

array of media object

optional

The media(s) in order to send file(s)

callback_url

string

optional

The URL is called when the request gets a response. Botdoc sends a POST with the Request Object

requester

Requester Object

optional

Requester information to be shown on the Request page and Completed page. If you don't pass any requester, the Requester information on the Request page will be the Owner’s profile information and blank on the Completed page of the application.

email_template_slug

string

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

tfa_send_to

enum

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

email In order to the Two Factor Authentication to an email

sms In order to the Two Factor Authentication to a mobile phone via SMS

tfa_send_to_value

string

optional

The value for the tfa_send_to

if the tfa_send_to is email. This value must be an valid email

if the tfa_send_to is sms. This value must be an mobile phone number in E.164 format

requester_privatenotes

type

is_draft

short_message

The small message up to 160 characters in order to send the SMS.
The URL to the request comes after the message

long_message_subject

string

optional

The message for the email Subject

long_message_subject

string

optional

The message for the email body

contact

array of contact object

optional

The contact(s) to send the request

media

array of media object

optional

The media(s) in order to send file(s)

callback_url

string

The URL is called when the request gets a response. Botdoc sends a POST with the Request Object

requester

Requester Object

Requester information to be shown on the Request page and Completed page. If you don't pass any requester, the Requester information on the Request page will be the Owner’s profile information and blank on the Completed page of the application.

email_template_slug

string

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

tfa_send_to

enum

optional

The slug of the email template. You have to create your email(s) template in the Botdoc developer dashboard.

email In order to the Two Factor Authentication to an email

sms In order to the Two Factor Authentication to a mobile phone via SMS

tfa_send_to_value

string

optional

The value for the tfa_send_to

if the tfa_send_to is email. This value must be an valid email

if the tfa_send_to is sms. This value must be an mobile phone number in E.164 format

The request_complete is a callback to let you know that the Push request has been expired, or the pull request has been responded to.

With this information you can take appropriate action inside your system, like letting the sender know that the Push request has been expired and no one actually downloaded the files, or the Pull request is complete and your system can start downloading the files,
remember the files from a pull request can only be downloaded one time from our servers, after that the file will be sent for removal.

The contact_notification_send callback will let you know when each of the contact methods (email or SMS) were sent out by our system,
if the status is not true, this means we had problems sending the request, this could be caused by many reasons, read the message parameter to understand better

Requesters

Requester is the user who is sending the request.
On the request page it will show the picture, or the initials as picture, the name and the role of the requester.
It's optional, you can create request without a requester, thus on request page with no requester will show the Profile User API.

Also on the request's completed page shows a few more fields, such as email, mobile phone, Facebook, Twitter, etc.

Formats

E.164 Phone Number

Every mobile is in E.164 format

E.164 is the international telephone numbering plan that ensures it has globally unique number. This is what allows text messages can be correctly routed to individual phones in different countries. E.164 numbers start with "+" plus the country code and follow the mobile number including area code with a maximum of 15 digits.

Examples:

E.164

Country Code

Country

Mobile

+14155552671

1

US

(415) 555-2671

+442071838750

44

GB

20718-38750

+551155256325

55

BR

(11) 95525-6325

Date and time

Format character

Description

Example output

Day

d

Day of the month, 2 digits with leading zeros.

01 to 31

j

Day of the month without leading zeros.

1 to 31

D

Day of the week, textual, 3 letters.

Fri

l

Day of the week, textual, long.

Friday

S

English ordinal suffix for day of the month, 2 characters.

st, nd, rd or th

w

Day of the week, digits without leading zeros.

0 (Sunday) to 6 (Saturday)

z

Day of the year.

0 to 365

Week

W

ISO-8601 week number of year, with weeks starting on Monday.

1, 53

Month

m

Month, 2 digits with leading zeros.

01 to 12

n

Month without leading zeros. style. Proprietary extension.

1 to 12

M

Month, textual, 3 letters.

Jan

b

Month, textual, 3 letters, lowercase.

jan

E

Month, locale specific alternative representation usually used for long date representation.

listopada (for Polish locale, as opposed to Listopad)

F

Month, textual, long.

January

N

Month abbreviation in Associated Press

Jan., Feb., March, May

t

Number of days in the given month.

28 to 31

Year

y

Year, 2 digits.

99

Y

Year, 4 digits.

1999

Time

g

Hour, 12-hour format without leading zeros.

1 to 12

G

Hour, 24-hour format without leading zeros.

0 to 23

h

Hour, 12-hour format.

01 to 12

H

Hour, 24-hour format.

00 to 23

i

Minutes.

00 to 59

s

Seconds, 2 digits with leading zeros.

00 to 59

u

Microseconds.

000000 to 999999

a

a.m. or p.m. (Note that includes periods to match Associated Press style.)

a.m.

A

AM or PM'.

AM'

f

Time, in 12-hour hours and minutes, with minutes left off if they're zero.

1, 1:30

P

Time, in 12-hour hours, minutes and a.m./p.m., with minutes left off if they're zero and the special-case strings midnight and noon if appropriate.

1 a.m., 1:30 p.m., midnight, noon, 12:30 p.m.

Timezone

e

Timezone name. Could be in any format, or might return an empty string, depending on the datetime.

'', 'GMT', '-500', 'US/Eastern', etc.

O

Difference to Greenwich time in hours.

+0200

T

Time zone of this machine.

EST, MDT

Z

Time zone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.

-43200 to 43200

Examples:

{{created|date:"D d M Y"}} output: Wed 09 Jan 2018

{{created|date:"d/m/Y"}} output: 09/01/2018

and you can also set the timezone:
{{created|timezone:"America/Denver"|date:"Y-m-d h:i a"}} output: 09/01/2018 11:30 a.m.

Report Issue

When submitting a report, please be as clear and concise as possible and make sure to include the exact steps or code to reproduce the bug. As developers you understand that the better you can detail the issue, the quicker we can locate and resolve it.

Community

The Stack Overflow community is a great place to ask API related questions or if you need help with your code. Make sure to tag your questions with the botdoc or botdoc-api tag to get fast answers from our developers and others.

Slack

Join us on Slack. Our public channel, a great place to communicate, ask questions, give feedback and get in touch with Botdoc Developer's team.