NAV Navbar
cURL
  • Get Started
  • Requests
  • Requesters
  • Medias
  • Contacts
  • Log
  • Objects
  • Formats
  • Developer Support
  • Changelogs
  • Get Started

    Overview

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

    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.

    To help you on Sandbox we do NOT charge you for any requests.

    To get started, go to https://sandboxdev.botdoc.io and create your first sandbox application.

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

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

    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

    Getting your token

    Endpoint get your token:

    Example Request

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --data '{  
       "api_key": "qwertyuioplkjhgfdsazxcvbnm",  
       "email": "email@domain.com"  
     }' 
     'https://api.botdoc.io/v1/auth/get_token'
    

    Example Response

    {
      "token": "mnbvcxzlkljhgfdsapoiuytrewq"
    }
    
    POST /{version}/auth/get_token/

    Request body

    • api_key

      string

      required

      The API Key

    • email

      string

      required

      The email of the application owner

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains:

    • token

      string

      Your access token that lasts for 8 hours

    Refresh token

    Endpoint to refresh your token:

    Example Request

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --data '{  
       "token": "mnbvcxzlkljhgfdsapoiuytrewq"
     }' 
     'https://api.botdoc.io/v1/auth/token_refresh/'
    

    Example Response

    {
      "token": "poiujmnhyytbbbvdaswdxhlkjwetgp"
    }
    
    POST /{version}/auth/token_refresh/

    Request body

    • token

      string

      required

      A valid token created within 7 days

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains:

    • token

      string

      Your new access token with a new expiration date

    Verify token

    You can verify if your token is still valid.

    Endpoint to verify your token:

    Example Request

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --data '{  
       "token": "poiujmnhyytbbbvdaswdxhlkjwetgp" 
     }' 
     'https://api.botdoc.io/v1/auth/token_verify/'
    

    Example Response

    {
      "token": "poiujmnhyytbbbvdaswdxhlkjwetgp"
    }
    
    POST /{version}/auth/token_verify/

    Request body

    • token

      string

      required

      The token

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains:

    • token

      string

      The same token if it is a valid token

    API requests

    In order to construct a REST API request, combine these components:

    Component Description
    The HTTP method
    • GET Request data from a resource
    • POST Submits data to a resource to process
    • PUT Updates a resource
    • PATCH Partially updates a resource
    • DELETE Delete a resource
    The URL to the Botdoc API service
    • Sandbox https://sandboxapi.botdoc.io
    • LIVE https://api.botdoc.io
    The URI to the resource The resource to query, submit data to, update, or delete.
    For example: v1/media
    Query parameters Optional. Controls which data appears in the response. For example: Use to filter, limit the size of, and sort the data in an API response.
    HTTP request headers The header to be included in the request
    A JSON request body Required for most GET, POST, PUT, and PATCH calls.

    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.

    HTTP status codes

    Each REST API request returns a success or error HTTP status code

    Success HTTP Status Code

    In the responses, Botdoc returns these HTTP status codes for successful requests:

    Status code Description
    200 OK The request succeeded.
    201 Created A POST method successfully created a resource.
    202 Accepted The server accepted the request and will execute it later.
    204 No Content The server successfully executed the method but returns no response body. For example: for the most DELETE calls

    Error HTTP Status Code

    In the responses for failed requests, Botdoc returns HTTP 4XX or 5XX status codes.

    For most errors, Botdoc returns an error response body that includes additional error details:

    Example Response when the email is not valid

    {
      "value": [
        "Not a valid email address"
      ]
    }
    

    In the responses, Botdoc returns these HTTP status codes for failed requests:

    HTTP status code Typical error code and error message Cause
    400 Bad Request INVALID REQUEST. Request is not well-formed, syntactically incorrect, or violates schema. See the validation errors. The server could not understand the request. Indicates one of these conditions:
    • The API cannot convert the payload data to the underlying data type.
    • The data is not in the expected data format.
    • A required field is not available.
    • A simple data validation error occurred.
    401 Unauthorized AUTHENTICATION FAILURE. Authentication failed due to invalid authentication credentials. 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.

    Endpoint to create a new request:

    Example Request to request files

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{  
       "message":"a nice message here",
       "requester_privatenotes":"private message here",
       "type":"pull",
       "short_message":"short message",
       "long_message":"a long message here",
       "contact":[  
          {  
             "first_name":"John",
             "last_name":"Doe",
             "contactmethod":[  
                {  
                   "interface_class":"email",
                   "value":"someone@email.com"
                }
             ]
          }
       ]
    }'
     'https://api.botdoc.io/v1/request/'
    

    Example Response when request files

    {  
       "id":9874564,
       "identifier":"b5f751c751d32d39xxxxxxxxxxxxxxxxxxx",
       "message":"a nice message here",
       "receiver_message":null,
       "requester_privatenotes":"private message here",
       "type":"pull",
       "is_draft":false,
       "complete":false,
       "short_message":"short message. https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/",
       "long_message_subject":"Jimmy Doe is requesting documents from you",
       "long_message":"a long message here. <a href=\"https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/\" target=\"_BLANK\">https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/</a>",
       "contact":[  
          {  
             "id":74453,
             "first_name":"John",
             "last_name":"Doe",
             "contactmethod":[  
                {  
                   "id":64547,
                   "interface_class":"email",
                   "value":"someone@email.com",
                   "created":"2018-01-25T18:20:02Z",
                   "updated":"2018-01-25T18:20:02Z"
                }
             ],
             "created":"2018-01-25T18:20:02Z",
             "updated":"2018-01-25T18:20:02Z"
          }
       ],
       "callback_url":null,
       "created":"2018-01-25T18:20:02.007141Z",
       "updated":"2018-01-25T18:20:02.007141Z"
    }
    
    
    
    POST /{version}/request/

    Request body

    • message

      string

      optional

      The message to be shown on request's page

    • requester_privatenotes

      string

      optional

      Your private notes

    • type

      enum

      optional

      The type of the request

      • push In order to send file(s)
      • pull In order to request file(s)

      Default: pull

    • is_draft

      boolean

      optional

      If the request is a draft or not

      Default: False

    • short_message

      string

      optional

      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
    • custom_config

      Custom Config Object

      optional

      A set of configuration when you want to override the Global Configuration for a specific request.

    Response

    A successful request returns the HTTP 201 OK status code and a JSON response body that lists payments with payment details.

    • identifier

      string

      The identifier

    • receiver_message

      string

      The respond message from the user

    • message

      string

      The message to be shown on request's page

    • requester_privatenotes

      string

      Your private notes

    • type

      enum

      The type of the request

      • push In order to send file(s)
      • pull In order to request file(s)
    • is_draft

      boolean

      If the request is a draft or not

    • short_message

      string

      optional

      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

    Requests Examples:

    Send request to an Email

    Simple example how to send a request to an email

    Request to email

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{
        "message": "a nice message here",
        "requestor_privatenotes": "your internal notes here",
        "type": "pull",
        "long_message_subject": "the subject email here",
        "long_message": "the body email message here",
        "contact": [{
            "first_name": "John",
            "last_name": "Doe",
            "contactmethod": [{
                "interface_class": "email",
                "value": "someone@email.com"
            }]
        }]
    }'
     'https://api.botdoc.io/v1/request/'
    

    Send request to a mobile

    Simple example how to send a request to a mobile

    Request to mobile

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{
        "message": "a nice message here",
        "requestor_privatenotes": "your internal notes here",
        "type": "pull",
        "short_message": "your sms message here",
        "contact": [{
            "first_name": "John",
            "last_name": "Doe",
            "contactmethod": [{
                "interface_class": "sms",
                "value": "+18185554709"
            }]
        }]
    }'
     'https://api.botdoc.io/v1/request/'
    

    Create a request with a Requester:

    First you have to create a Requesters, then just assign the ID.

    Request with Requester

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{  
       "message":"a nice message here",
       "requester_privatenotes":"private message here",
       "type":"pull",
       "long_message_subject": " Subject email here"
       "long_message":"Body message here",
       "requester": {
            "id": 8965
       }
       "contact":[  
          {  
             "first_name":"John",
             "last_name":"Doe",
             "contactmethod":[  
                {  
                   "interface_class":"email",
                   "value":"someone@email.com"
                }
             ]
          }
       ]
    }'
     'https://api.botdoc.io/v1/request/'
    

    Create a request with a Two Factor Authentication:

    Simple example how to send a request with a Two Factor Authentication (TFA)

    Request with a Two Factor Authentication:

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{  
       "message":"a nice message here",
       "requester_privatenotes":"private message here",
       "type":"pull",
       "long_message_subject": " Subject email here"
       "long_message":"Body message here",
       "contact":[  
          {  
             "first_name":"John",
             "last_name":"Doe",
             "contactmethod":[  
                {  
                   "interface_class":"email",
                   "value":"someone@email.com"
                }
             ]
          }
       ],
       "tfa_send_to": "sms",
       "tfa_send_to_value": "+18885554789"
    }'
     'https://api.botdoc.io/v1/request/'
    

    Send Notification

    Endpoint to send the notification to your contact.

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/request/9874564/send_notification/'
    

    Example Response

    {
      "contact_notification_send": [
        {
          "id": 523423,
          "sent_at": "2018-06-27T16:44:06.895Z",
          "contactmethod": {
            "id": 3231,
            "interface_class": "email",
            "value": "someone@email.com"
          }
        },
        {
          "id": 523424,
          "sent_at": "2018-06-27T16:44:08.463Z",
          "contactmethod": {
            "id": 3445,
            "interface_class": "email",
            "value": "another_email@email.com"
          }
        },
        {
          "id": 523425,
          "sent_at": "2018-06-27T16:44:09.267Z",
          "contactmethod": {
            "id": 954,
            "interface_class": "sms",
            "value": "+18885554789"
          }
        }
      ],
      "contact_notification_failed": [
        {
          "contactmethod": {
            "id": 86987,
            "interface_class": "email",
            "value": "email@email.com"
          }
        }
      ]
    }
    
    POST /{version}/request/{id}/send_notification/

    Path parameters

    • id

      integer

      required

      The request ID

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains.

    • contact_notification_send

      array of Contact Notification Send Object

    • contact_notification_failed

      array of Contact Notification Failed Object

    Get the total of your requests

    Endpoint to get the total of your requests sent by your account

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/request/counter/'
    

    Example Response

    {
        "count": 1547
    }
    
    GET /{version}/request/counter/

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains.

    • counter

      integer

      The total of requests

    Listing your requests

    Endpoint to get a list of all requests in your account:

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/request/?page=2&page_size=5'
    

    Example Response

    {  
       "links":{  
          "previous":"https://api.botdoc.io/v1/request/?page_size=5",
          "next":"https://api.botdoc.io/v1/request/?page=3&page_size=5"
       },
       "total_pages":4,
       "count":18,
       "results":[  
            {  
                "id":5457,
                "identifier":"820aeeb52ad0707xxxxxxxxxxxxxxxxx",
                ...
            },
            ...
            {
             "id":5459,
             "identifier":"b63202468ca4cb029fxxxxxxxxxxxxxxxxxb",
             ...
            }      
       ]
    }
    
    GET /{version}/request/

    Query parameters

    • page

      Integer

      optional

      A page number within the paginated result set

      Default: 1

    • page_size

      Integer

      optional

      Number of results to return per page.

      Default: 10

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains.

    • links

      integer

      Array of Link Object

    • total_pages

      integer

      The total pages

    • count

      integer

      The total of requests

    • results

      Array of Request Object

    Get request's information

    Endpoint to get the information about a specific request

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/request/4578/'
    

    Example Response

    
    {  
       "id":4578,
       "identifier":"c0ea665eefe04exxxxxxxxxxxxxxxxx",
       "message":"a nice message here",
       "receiver_message":"the response message here",
       "requester_privatenotes":"my private message here",
       "type": "pull",
       "is_draft":false,
       "complete":true,
       "short_message": "a short message here. https://sandboxapi.botdoc.io/r/c0ea665eefe04exxxxxxxxxxxxxxxxx/",
       "long_message_subject":"Jimmy Doe is requesting documents from you",
       "long_message":"a long message here. <a href=\"https://api.botdoc.io/r/c0ea665eefe04exxxxxxxxxxxxxxxxx/\" target=\"_BLANK\">https://api.botdoc.io/r/c0ea665eefe04exxxxxxxxxxxxxxxxx/</a>",
       "contact":[  
          {  
             "id":9,
             "first_name":"John",
             "last_name":"Doe",
             "contactmethod":[  
                {  
                   "id":16,
                   "interface_class":"email",
                   "value":"someone@email.com",
                   "created":"2018-01-24T19:12:35Z",
                   "updated":"2018-01-24T19:12:35Z"
                }
             ],
             "created":"2018-01-24T19:12:35Z",
             "updated":"2018-01-24T19:12:35Z"
          }
       ],
       "media":[  
          {  
             "id":33,
             "request":80,
             "name":"image.png",
             "content_type":"image/png",
             "bytes":71693,
             "extension":"png",
             "file":"45a8941c82ed10d0xxxxxxxxxxxxxxxx.png",
             "created":"2018-01-24T19:25:50Z",
             "updated":"2018-01-24T19:25:50Z"
          },
          {  
             "id":34,
             "request":80,
             "name":"business_plan.docx",
             "content_type":"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "bytes":15091,
             "extension":"docx",
             "file":"9e527bbe00fa950xxxxxxxxxxxxxxxx.docx",
             "created":"2018-01-24T19:25:52Z",
             "updated":"2018-01-24T19:25:52Z"
          }
       ],
       "callback_url":null,
       "created":"2018-01-24T19:25:28Z",
       "updated":"2018-01-24T19:26:10Z"
    }
    
    GET /{version}/request/{id}/

    Path parameters

    • id

      string

      required

      The request ID

    Response

    A successful request returns the HTTP 201 OK status code and a JSON response body that lists payments with payment details.

    • id

      integer

      The request ID

    • identifier

      string

      The identifier

    • receiver_message

      string

      The respond message from the user

    • message

      string

      The message to be shown on request's page

    • requester_privatenotes

      string

      Your private notes

    • type

      enum

      The type of the request

      • push In order to send file(s)
      • pull In order to request file(s)
    • is_draft

      boolean

      If the request is a draft or not

    • short_message

      string

      optional

      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

    Update request's information

    Example Request to request files

    curl --request PATCH 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{  
       "long_message":"ANOTHER long message here"
    }'
     'https://api.botdoc.io/v1/request/9874564'
    

    Example Response when request files

    {  
       "id":9874564,
       "identifier":"b5f751c751d32d39xxxxxxxxxxxxxxxxxxx",
       "message":"a nice message here",
       "receiver_message":null,
       "requester_privatenotes":"private message here",
       "type":"pull",
       "is_draft":false,
       "complete":false,
       "short_message":"short message. https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/",
       "long_message_subject":"Jimmy Doe is requesting documents from you",
       "long_message":"ANOTHER long message here <a href=\"https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/\" target=\"_BLANK\">https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/</a>",
       "contact":[  
          {  
             "id":74453,
             "first_name":"John",
             "last_name":"Doe",
             "contactmethod":[  
                {  
                   "id":64547,
                   "interface_class":"email",
                   "value":"someone@email.com",
                   "created":"2018-01-25T18:20:02Z",
                   "updated":"2018-01-25T18:20:02Z"
                }
             ],
             "created":"2018-01-25T18:20:02Z",
             "updated":"2018-01-25T18:20:02Z"
          }
       ],
       "media":[  
       ],
       "callback_url":null,
       "created":"2018-01-25T18:20:02.007141Z",
       "updated":"2018-01-25T18:20:02.007141Z"
    }
    

    Endpoint to update request's information:

    PATCH /{version}/request/{id}

    Request body

    • message

      string

      optional

      The message to be shown on request's page

    • requester_privatenotes

      string

      optional

      Your private notes

    • type

      enum

      optional

      The type of the request

      • push In order to send file(s)
      • pull In order to request file(s)

      Default: pull

    • is_draft

      boolean

      optional

      If the request is a draft or not

      Default: False

    • short_message

      string

      optional

      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

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that lists payments with payment details.

    • identifier

      string

      The identifier

    • receiver_message

      string

      The respond message from the user

    • message

      string

      The message to be shown on request's page

    • requester_privatenotes

      string

      Your private notes

    • type

      enum

      The type of the request

      • push In order to send file(s)
      • pull In order to request file(s)
    • is_draft

      boolean

      If the request is a draft or not

    • short_message

      string

      optional

      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

    Delete a request

    Endpoint to delete a specific request

    Example Request

    curl --request DELETE 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/request/6589/'
    

    No Content Body Response

    DELETE /{version}/request/{id}/

    Path parameters

    • id

      integer

      required

      The request ID

    Response

    A successful request returns the HTTP 204 No Content status code.

    Callbacks

    When the callback_url parameter is sent in the request creation, the same URL sent to this parameter will start receiving callbacks related to the request.

    There are two types of call back The Callback to contact_notification_send and the callback request_complete both work the same but they serve different purposes.

    Callback type "request_complete"

    Example Callback type request_complete

    {  
        "type": "request_complete",
        "request": {
            "id":9874564,
            "identifier":"b5f751c751d32d39xxxxxxxxxxxxxxxxxxx",
            "message":"a nice message here",
            "receiver_message":null,
            "requester_privatenotes":"private message here",
            "type":"pull",
            "is_draft":false,
            "complete":true,
            "short_message":"short message. https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/",
            "long_message_subject":"John Doe is requesting documents from you",
            "long_message":"a long message here. <a href=\"https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/\" target=\"_BLANK\">https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/</a>",
            "contact":[  
                {  
                    "id":74453,
                    "first_name":"John",
                    "last_name":"Doe",
                    "contactmethod":[  
                        {  
                        "id":64547,
                        "interface_class":"email",
                        "value":"someone@email.com",
                        "created":"2018-01-25T18:20:02Z",
                        "updated":"2018-01-25T18:20:02Z"
                        }
                    ],
                    "created":"2018-01-25T18:20:02Z",
                    "updated":"2018-01-25T18:20:02Z"
                }
            ],
            "callback_url":"https://yoururl.com/botdoc/callback/",
            "created":"2018-01-25T18:20:02.007141Z",
            "updated":"2018-01-25T18:20:02.007141Z",
        }
    }
    

    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.

    Callback type "contact_notification_send"

    Example Callback type contact_notification_send

    {  
        "type": "contact_notification_send",
        "message": "success",
        "status": true,
        "notification": {
            "id":9874564,
            "was_sent": true,
            "removed": false,
            "contact_first_name": "John",
            "contact_last_name": "Doe",
            "contact_method_value": "someone@email.com",
            "contact_method_interface_class": "email",
            "created":"2018-01-25T18:20:02.007141Z",
            "updated":"2018-01-25T18:20:02.007141Z",
        },
        "request": {
            "id":9874564,
            "identifier":"b5f751c751d32d39xxxxxxxxxxxxxxxxxxx",
            "message":"a nice message here",
            "receiver_message":null,
            "requester_privatenotes":"private message here",
            "type":"pull",
            "is_draft":false,
            "complete":false,
            "short_message":"short message. https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/",
            "long_message_subject":"John Doe is requesting documents from you",
            "long_message":"a long message here. <a href=\"https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/\" target=\"_BLANK\">https://api.botdoc.io/r/b5f751c751d32d39xxxxxxxxxxxxxxxxxxx/</a>",
            "contact":[  
                {  
                    "id":74453,
                    "first_name":"John",
                    "last_name":"Doe",
                    "contactmethod":[  
                        {  
                        "id":64547,
                        "interface_class":"email",
                        "value":"someone@email.com",
                        "created":"2018-01-25T18:20:02Z",
                        "updated":"2018-01-25T18:20:02Z"
                        }
                    ],
                    "created":"2018-01-25T18:20:02Z",
                    "updated":"2018-01-25T18:20:02Z"
                }
            ],
            "callback_url":"https://yoururl.com/botdoc/callback/",
            "created":"2018-01-25T18:20:02.007141Z",
            "updated":"2018-01-25T18:20:02.007141Z",
        }
    }
    

    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.

    This endpoint is in order to manage your requesters.

    Create Requester

    Endpoint to create a new requester:

    Example Request

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{
      "first_name": "John",
      "last_name": "Doe",
      "company": "John Doe Business",
      "role": "Manager",
      "email": "johndoe@email.com",
      "mobile": "847 555 6984",
      "location": "Monument, CO",
      "twitter": "johndoe",
      "skype": "johndoe",
      "facebook": "johndoe",
      "linkedin": "johndoe"
    }'
     'https://api.botdoc.io/v1/requester/'
    

    Example Response when request files

    {
      "id": 465715,
      "first_name": "John",
      "last_name": "Doe",
      "role": "Manager",
      "email": "johndoe@email.com",
      "company": "John Doe Business",
      "mobile": "847 555 6984",
      "location": "Monument, CO",
      "skype": "johndoe",
      "linkedin": "johndoe",
      "facebook": "johndoe",
      "twitter": "johndoe",
      "avatar": null,
      "created": "2018-02-13T20:08:01.781170Z",
      "updated": "2018-02-13T20:08:01.781170Z"
    }
    
    
    
    POST /{version}/requester/

    Request body

    • first_name

      string

      required

      The Requester first name

    • last_name

      string

      required

      The Requester last name

    • email

      string

      required

      The Requester email

    • mobile

      string

      optional

      A mobile phone in E.164 format

    • company

      string

      optional

      The company's name

    • role

      string

      optional

      The role

    • location

      string

      optional

      The location

    • facebook

      string

      optional

      The Facebook username

    • linkedin

      string

      optional

      The Linkedin username, without @ at the beginning

    • twitter

      string

      optional

      The Twitter username, without @ at the beginning

    • avatar

      string

      optional

      The image file content

    • skype

      string

      optional

      The Skype username

    Response

    A successful request returns the HTTP 201 OK status code and a JSON response body that lists payments with payment details.

    • id

      integer

      The Requester ID

    • first_name

      string

      The Requester first name

    • last_name

      string

      The Requester last name

    • email

      string

      The Requester email

    • mobile

      string

      A mobile phone in E.164 format

    • company

      string

      The company's name

    • role

      string

      The role

    • location

      string

      The location

    • facebook

      string

      The Facebook username

    • linkedin

      string

      The Linkedin username, without @ at the beginning

    • twitter

      string

      The Twitter username, without @ at the beginning

    • avatar

      string

      The image file content

    • skype

      string

      The skype username

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Listing your requesters

    Endpoint to get a list of all requesters in your account:

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/requester/?page=2&page_size=5'
    

    Example Response

    {  
       "links":{  
          "previous":"https://api.botdoc.io/v1/requester/?page_size=5",
          "next":"https://api.botdoc.io/v1/requester/?page=3&page_size=5"
       },
       "total_pages":4,
       "count":18,
       "results":[  
            {  
                "id":5457,            
                ...
            },
            ...
            {
             "id":5459,         
             ...
            }      
       ]
    }
    
    GET /{version}/requester/

    Query parameters

    • page

      Integer

      optional

      A page number within the paginated result set

      Default: 1

    • page_size

      Integer

      optional

      Number of results to return per page.

      Default: 10

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains.

    • links

      integer

      Array of Link Object

    • total_pages

      integer

      The total pages

    • count

      integer

      The total of requesters

    • results

      Array of Requester Object

    Get requester's information

    Endpoint to get the information about a specific requester

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/requester/465715/'
    

    Example Response

    
    
    {
      "id": 465715,
      "first_name": "John",
      "last_name": "Doe",
      "role": "Manager",
      "email": "johndoe@email.com",
      "company": "John Doe Business",
      "mobile": "847 555 6984",
      "location": "Monument, CO",
      "skype": "johndoe",
      "linkedin": "johndoe",
      "facebook": "johndoe",
      "twitter": "johndoe",
      "avatar": null,
      "created": "2018-02-13T20:08:01.781170Z",
      "updated": "2018-02-13T20:08:01.781170Z"
    }
    
    GET /{version}/requester/{id}/

    Path parameters

    • id

      integer

      required

      The Requester ID

    Response

    A successful request returns the HTTP 201 OK status code and a JSON response body that lists payments with payment details.

    • id

      integer

      The Requester ID

    • first_name

      string

      The Requester first name

    • last_name

      string

      The Requester last name

    • email

      string

      The Requester email

    • mobile

      string

      A mobile phone in E.164 format

    • company

      string

      The company's name

    • role

      string

      The role

    • location

      string

      The location

    • facebook

      string

      The Facebook username

    • linkedin

      string

      The Linkedin username, without @ at the beginning

    • twitter

      string

      The Twitter username, without @ at the beginning

    • avatar

      string

      The image file content

    • skype

      string

      The skype username

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Update requester's information

    Endpoint to modify partial requester\'s information:

    Example Request

    curl --request PATCH 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{
      "first_name": "Jimmy",
    }'
     'https://api.botdoc.io/v1/requester/465715'
    

    Example Response when request files

    {
      "id": 465715,
      "first_name": "Jimmy",
      "last_name": "Doe",
      "role": "Manager",
      "email": "johndoe@email.com",
      "company": "John Doe Business",
      "mobile": "847 555 6984",
      "location": "Monument, CO",
      "skype": "johndoe",
      "linkedin": "johndoe",
      "facebook": "johndoe",
      "twitter": "johndoe",
      "avatar": null,
      "created": "2018-02-13T20:08:01.781170Z",
      "updated": "2018-02-13T20:08:01.781170Z"
    }
    
    PATCH /{version}/requester/

    Request body

    • first_name

      string

      required

      The Requester first name

    • last_name

      string

      required

      The Requester last name

    • email

      string

      required

      The Requester email

    • mobile

      string

      optional

      A mobile phone in E.164 format

    • company

      string

      optional

      The company's name

    • role

      string

      optional

      The role

    • location

      string

      optional

      The location

    • facebook

      string

      optional

      The Facebook username

    • linkedin

      string

      optional

      The Linkedin username, without @ at the beginning

    • twitter

      string

      optional

      The Twitter username, without @ at the beginning

    • avatar

      string

      optional

      The image file content

    • skype

      string

      optional

      The skype username

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that lists payments with payment details.

    • id

      integer

      The Requester ID

    • first_name

      string

      The Requester first name

    • last_name

      string

      The Requester last name

    • email

      string

      The Requester email

    • mobile

      string

      A mobile phone in E.164 format

    • company

      string

      The company's name

    • role

      string

      The role

    • location

      string

      The location

    • facebook

      string

      The Facebook username

    • linkedin

      string

      The Linkedin username, without @ at the beginning

    • twitter

      string

      The Twitter username, without @ at the beginning

    • avatar

      string

      The image file content

    • skype

      string

      The skype username

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Delete a requester

    Endpoint to delete a specific requester

    Example Request

    curl --request DELETE 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/requester/465715/'
    

    No Content Body Response

    DELETE /{version}/requester/{id}/

    Path parameters

    • id

      integer

      required

      The Requester ID

    Response

    A successful request returns the HTTP 204 No Content status code.

    Medias

    Medias are files encrypted that you can download or send them to your customers.

    Create Medias

    When you create a request with is_draft = true, you can create media and assign to this request and after you finish to upload every file you need, you can send the request.

    You can either send the complete file or you can send splitted in multiples chunks of 4mb.

    e.g.:

    You have a 10gb file:
    You can send one request containing the entire 10gb.
    Or
    You send 2500 requests, one for each chunk, being the first as POST and the rest as PUT

    Endpoint to create a new media:

    Example Request

    curl --request POST 
    --header 'Content-Type: application/x-www-form-urlencoded' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{
      "request": 65265,
      "content_type": "image/png",
      "name": "photo.png",
      "file": "the binary here"
    }'
     'https://api.botdoc.io/v1/media/'
    

    Example Response

    {  
       "id":98463285,
       "request":65265,
       "name":"photo.png",
       "content_type":"image/png",
       "bytes":959888,
       "extension":"png",
       "created":"2018-01-31T18:59:14Z",
       "updated":"2018-01-31T18:59:14Z"
    }
    
    
    
    POST /{version}/media/

    Request body

    • request

      integer

      required

      The request ID

    • content_type

      string

      required

      The content type

    • name

      string

      required

      The name of the file with extension

    • file

      string

      required

      The binary

    • total_chunks

      integer

      optional

      Integer with the total number of chunks

    • current_chunk

      integer

      optional

      Integer with the current chunk number

    Response

    A successful request returns the HTTP 201 Created status code and a JSON response body that contains:

    • id

      integer

      The Media ID

    • request

      integer

      The request ID

    • content_type

      string

      The content type

    • name

      string

      The name of the file with extension

    • bytes

      integer

      The file size in bytes

    • extension

      string

      The extension

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Sending Chunks

    When you create a media with total_chunks bigger than one, you have to send a PUT request for each chunk with the current_chunk.

    Endpoint to send a your chunks:

    Example Request

    curl --request PUT 
    --header 'Content-Type: application/x-www-form-urlencoded' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{
      "file": "the binary here"
      "current_chunk": 35,
    }'
     'https://api.botdoc.io/v1/media/'
    

    Example Response

    {  
       "id":98463285,   
    }
    
    
    
    PUT /{version}/media/{media_id}

    Path parameters

    • id

      integer

      required

      The media ID

    Request body

    • file

      string

      required

      The binary with a 4mb limit for each chunk

    • current_chunk

      integer

      required

      The current number of chunks.

    Response

    A successful request returns the HTTP 201 Created status code and a JSON response body that contains:

    • id

      integer

      The Media ID

    • request

      integer

      The request ID

    • content_type

      string

      The content type

    • name

      string

      The name of the file with extension

    • bytes

      integer

      The file size in bytes

    • extension

      string

      The extension

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Listing your medias

    Endpoint to get a list of all the Medias/Files in your account:

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/media/?page=2&page_size=5'
    

    Example Response

    {  
       "links":{  
          "previous":"https://api.botdoc.io/v1/media/?page_size=5",
          "next":"https://api.botdoc.io/v1/request/?media=3&page_size=5"
       },
       "total_pages":4,
       "count":18,
       "results":[  
            {  
                "id":52145,
                "request":9685,
                ...
          },
          ...
          {  
            "id":52146,
            "request":9685,       
            ...  
          }      
       ]
    }
    
    GET /{version}/media/

    Query parameters

    • page

      Integer

      optional

      A page number within the paginated result set

      Default: 1

    • page_size

      Integer

      optional

      Number of results to return per page.

      Default: 10

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains.

    • links

      integer

      Array of Link Object

    • total_pages

      integer

      The total pages

    • count

      integer

      The total of medias

    • results

      Array of Media Object

    Get Media's information

    Endpoint to get the information about a specific media

    This endpoint does NOT retrieve the file's content. In order to do so, you have to use the endpoint below, Download media.

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/media/6543321/'
    

    Example Response

    {  
       "id":6543321,
       "request":944256354,
       "name":"image.png",
       "content_type":"image/png",
       "bytes":46558,
       "extension":"png",
       "created":"2018-01-25T18:59:14Z",
       "updated":"2018-01-25T18:59:14Z"
    }
    
    GET /{version}/media/{id}/

    Path parameters

    • id

      integer

      required

      The media ID

    Response

    A successful request returns the HTTP 20 OK status code and a JSON response body that contains:

    • id

      integer

      The Media ID

    • request

      integer

      The request ID

    • content_type

      string

      The content type

    • name

      string

      The name of the file with extension

    • bytes

      integer

      The file size in bytes

    • extension

      string

      The extension

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Download media

    Endpoint to download a specific media

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/media/6543321/download/'
    

    The body response is the file's content

    GET /{version}/media/{id}/download

    Path parameters

    • id

      integer

      required

      The media ID

    Response

    A successful request returns the HTTP 200 OK status code and the file's content in the response body.

    Media integrity check

    Endpoint to perform integrity check on a downloaded media.

    When you download a media, you must perform an integrity check in the downloaded media in order to guarantee the integrity of your file and, provide Botdoc a feedback when that media can be removed safely.
    The integrity check is a mandatory step in your integration for push requests and, it is for the best interest of our users to perform this step since we only erase the media permanently from Botdoc once this verification is completed.

    Example Request

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/media/6543321/integrity_check/'
    --data '{
      "file_checksum": "1a79a4d60de6718e8e5b326e338ae533",
    }'
    

    Example Response

    {  
       "id":6543321,
       "request":65265,
       "name":"photo.png",
       "content_type": "image/png",
       "bytes":959888,
       "extension":"png",
       "file_checksum": "1a79a4d60de6718e8e5b326e338ae533",
       "file": "98fe36ce9a6f6fd548d6b9948cfc7688.png",
       "current_chunk": 1,
       "total_chunks": 1,
       "upload_complete": 1,
       "is_available": 1,
       "metadata": {
          "remote_addr": ""
       },
       "times_downloaded": 1,
       "max_allowed_times_downloaded": 6,
       "media_download": [{
          "start": "2019-03-01T19:01:42.820412Z",
          "end": "2019-03-01T19:01:45.347410Z",
          "remote_addr": "",
          "total_bytes": 58774,
          "downloaded_bytes": 58774,
          "download_completed": 1,
          "updated": "2019-03-01T19:01:45.348411Z",
          "created": "2019-03-01T19:01:42.820412Z",
       }],
       "removed_at": "",
       "removed_requested_from": "",
       "safe_to_remove": 1,
       "created": "2019-03-01T19:01:17.660730Z",
       "updated": "2019-03-01T19:01:45.829414Z"
    }
    
    POST /{version}/media/{id}/integrity_check/

    Path parameters

    • id

      integer

      required

      The media ID

    Request body

    • file_checksum

      string

      required

      The file_checksum is a MD5 hash hexadecimal (32 characters length) format of your entire content media.

      If the file_checksum matches with Botdoc, it means you received the entire media content correctly and the media can be safely removed on Botdoc end. Otherwise you may have sent the wrong file_checksum or something went wrong during the download.

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains:

    • id

      integer

      The Media ID

    • request

      integer

      The request ID

    • name

      string

      The name of the file with extension

    • content_type

      string

      The content type

    • bytes

      integer

      The file size in bytes

    • extension

      string

      The extension

    • file_checksum

      string

      The file_checksum

    • file

      string

      File name and extension

    • current_chunk

      integer

      Integer with the current chunk number

    • total_chunks

      integer

      Integer with the total number of chunks

    • upload_complete

      integer

      if the upload is completed

    • is_available

      integer

      if the media is available

    • metadata

      metadata object

      The metadata

    • times_downloaded

      integer

      How many times the media was downloaded

    • max_allowed_times_downloaded

      integer

      The max allowed amount to download the media

    • media_download

      array of media download objects

      The list of medias download object

    • removed_at

      string

      if not null, the datetime when it was removed using the Y-m-d\TH:i:s\Z format

    • removed_at

      string

      if not null, who requested the media to be removed

    • safe_to_remove

      integer

      If the integrity check was submitted successfully, the media is safe to be removed on Botdoc side.

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Delete a media

    Endpoint to delete a specific media

    Example Request

    curl --request DELETE 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/media/35485/'
    

    No Content Body Response

    DELETE /{version}/media/{id}/

    Path parameters

    • id

      integer

      required

      The media ID

    Response

    A successful request returns the HTTP 204 No Content status code.

    Contacts

    Create new Contact

    Endpoint to create a new request:

    Example Request

    curl --request POST 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{"first_name":"John","last_name":"Doe188537"}"'
     'https://api.botdoc.io/v1/contact/'
    

    Example Response

    {  
       "id":7,
       "first_name":"John",
       "last_name":"Doe188537",
       "contactmethod":[  
    
       ],
       "created":"2018-01-23T19:29:46.657892Z",
       "updated":"2018-01-23T19:29:46.657892Z"
    }
    
    POST /{version}/contact/

    Request body

    • first_name

      string

      optional

      The Contact first name

    • last_name

      string

      optional

      The Contact last name

    • contactmethod

      Array of Contact Method Object

      optional

    Response

    A successful request returns the HTTP 201 Created status code and a JSON response body that contains:

    • id

      integer

      The Contact ID

    • first_name

      string

      The Contact first name

    • last_name

      string

      The Contact last name

    • contactmethod

      Array of Contact Method Object

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Listing your contacts

    Endpoint to get a list of all contacts in your account:

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/contact/?page=2&page_size=5'
    

    Example Response

    {  
       "links":{  
          "previous":"https://api.botdoc.io/v1/contact/?page_size=5",
          "next":"https://api.botdoc.io/v1/contact/?page=3&page_size=5"
       },
       "total_pages":4,
       "count":18,
       "results":[  
          {  
             "id":7,
             "first_name":"John",
             "last_name":"Doe-407829679",
             "contactmethod":[  
    
             ],
             "created":"2018-01-23T18:23:10Z",
             "updated":"2018-01-23T18:23:10Z"
          },
          ...
          {  
             "id":8,
             "first_name":"John",
             "last_name":"Doe-1718084559",
             "contactmethod":[  
    
             ],
             "created":"2018-01-23T18:23:13Z",
             "updated":"2018-01-23T18:23:13Z"
          }
       ]
    }
    
    GET /{version}/contact/

    Query parameters

    • page

      Integer

      optional

      A page number within the paginated result set

      Default: 1

    • page_size

      Integer

      optional

      Number of results to return per page.

      Default: 10

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains.

    • links

      integer

      Array of Link Object

    • total_pages

      integer

      The total pages

    • count

      integer

      The total of contact

    • results

      Array of Contact Object

    Get Contact's information

    Endpoint to get the information about a specific contact

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/contact/7/'
    

    Example Response

    {  
       "id":7,
       "first_name":"John",
       "last_name":"Doe",
       "contactmethod":[  
    
       ],
       "created":"2018-01-23T19:29:46.657892Z",
       "updated":"2018-01-23T19:29:46.657892Z"
    }
    
    GET /{version}/contact/{id}/

    Path parameters

    • id

      integer

      required

      The Contact ID

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains:

    • id

      integer

      The Contact ID

    • first_name

      string

      The Contact first name

    • last_name

      string

      The Contact last name

    • contactmethod

      Array of Contact Method Object

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Update contact's information

    Endpoint to modify partial contact's information:

    Example Request

    curl --request PATCH 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
    --data '{"last_name":"Doe-64214"}"'
     'https://api.botdoc.io/v1/contact/7/'
    

    Example Response

    {  
       "id":7,
       "first_name":"John",
       "last_name":"Doe-64214",
       "contactmethod":[  
    
       ],
       "created":"2018-01-23T19:29:46.657892Z",
       "updated":"2018-01-24T18:04:52.272486Z"
    }
    
    PATCH /{version}/contact/{id}/

    Path parameters

    • id

      string

      optional

      The Contact ID

    Request body

    • first_name

      string

      optional

      The Contact first name

    • last_name

      string

      optional

      The Contact last name

    • contactmethod

      Array of Contact Method Object

      optional

    Response

    A successful request returns the HTTP 201 Created status code and a JSON response body that contains:

    • id

      integer

      The Contact ID

    • first_name

      string

      The Contact first name

    • last_name

      string

      The Contact last name

    • contactmethod

      Array of Contact Method Object

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was the last updated using the Y-m-d\TH:i:s\Z format

    Delete a contact

    Endpoint to delete a specific contact

    Example Request

    curl --request DELETE 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/contact/5/'
    

    No Content Body Response

    DELETE /{version}/contact/{id}/

    Path parameters

    • id

      integer

      required

      The contact ID

    Response

    A successful request returns the HTTP 204 No Content status code.

    Log

    Botdoc records events taking place in the execution in order to provide an audit trail that can be used to understand the activity of the system and to diagnose problems.

    Endpoint to get a list of all the Logs:

    Example Request

    curl --request GET 
    --header 'Content-Type: application/json' 
    --header 'Accept: application/json' 
    --header 'Authorization: JWT poiujmnhyytbbbvdaswdxhlkjwetgp'
     'https://api.botdoc.io/v1/logentry/search/?page=2&page_size=5'
    

    Example Response

    {
      "next_marker": {
        "nextpartitionkey": "{\"token\":\"+RID:3dBxAPmeGACpJgAAAAAAAA==#RT:1#TRC:100#FPC:AgEAAAAKAKEmAP4iQD+AAwA=\",\"range\":{\"min\":\"\",\"max\":\"FF\"}}",
        "nextrowkey": "{\"token\":\"+RID:3dBxAPmeGACpJgAAAAAAAA==#RT:1#TRC:100#FPC:AgEAAAAKAKEmAP4iQD+AAwA=\",\"range\":{\"min\":\"\",\"max\":\"FF\"}}"
      },
      "results": [
        {
          "PartitionKey": "user_activities",
          "RowKey": "d903a30c-b8eb-4bcb-972b-ceba24e09780",
          "Timestamp": "2018-07-23T17:39:41.339Z",
          "code": "AAA-0001",
          "api_key_id": "dd8f911a-2979-4120-b7b7-4489cd3591d6",
          "related_model": "User",
          "relation_key": "1",
          "value": "User login successful",
          "from": "127.0.0.1",
          "method": "None",
          "path": "None",
          "data": "{}",
          "content_type": "None",
          "etag": "W/\"datetime'2018-07-23T17%3A39%3A41.3394619Z'\""
        },
        ...
        ]
    }
    
    GET /{version}/logentry/search/

    Query parameters

    • page

      Integer

      optional

      A page number within the paginated result set

      Default: 1

    • page_size

      Integer

      optional

      Number of results to return per page.

      Default: 100

      Maximum value: 100

    • marker

      String

      optional

      The marker tells the search where to start the pagination.

    • PartitionKey

      String

      optional

      Filter by PartitionKey

    • code

      String

      optional

      Filter by Code

    • related_model

      String

      optional

      Filter by Related Model

    • path

      String

      optional

      Filter by Path

    • from

      String

      optional

      Filter by From

    • method

      String

      optional

      Filter by method

    • content_type

      String

      optional

      Filter by content type

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that contains.

    • next_marker

      Marker Object

    • total_pages

      integer

      The total pages

    • results

      Array of Log Object

    codes

    code description
    AAA-0010 Log the calls made to the API endpoints
    AAA-0011 Log the calls made to the fetch/send pages
    ABB-0010 Log when a media is downloaded
    ABA-0010 Log when entities are created
    ABA-0020 Log when entities are deleted
    ABA-0030 Log when entities are updated
    ABB-0020 Log when an user loads the page of fetch/send files
    ABD-0010 Log when the request email is opened
    ABC-0010 Log when a request it sent to the contact_methods within that request
    AAA-0002 Log when a fail user login occurs
    AAA-0001 Log when a successful user login occurs

    Objects

    Example

    {  
      "previous":"https://api.botdoc.io/v1/request/?page_size=5",
      "next":"https://api.botdoc.io/v1/request/?page=3&page_size=5"   
    }
    
    • previous

      string

      The URL to get the previous page. Empty if it is the first page.

    • next

      string

      The URL to get the next page. Empty if it is the last page.

    Custom Config

    Example

    {  
      "custom_config": [
            {
                "name": "request_config/minutes_to_push_expire",
                "value": 200
            },
            {
                "name": "request_config/minutes_to_pull_expire",
                "value": 200
            },
            {
                "name": "request_config/push_download_limit",
                "value": 3
            }
        ]
    }
    
    • name

      string

      The code of the configuration.

    • value

      mix

      The value to override the configuration. The value type is based on the name.

    types

    • request_config/minutes_to_push_expire

      int

      Set the date and time expiration in minutes counting since when the first request notification was sent.

    • request_config/minutes_to_pull_expire

      int

      Set the date and time expiration in minutes counting since when the first request notification was sent.

    • request_config/push_download_limit

      int

      How many times the client can download each file in a `push` request.

    Contact Method

    Example Email

    {  
      "interface_class":"email",
      "value":"someone@email.com"   
    }
    

    Example Mobile Phone

    {
        "interface_class": "sms",
        "value": "+18185554709"
    }
    
    • interface_class

      enum

      The interface class of the contact method

      • email In order to send to an email
      • sms In order to send to a mobile phone via SMS
    • value

      string

      The value based on the interface class

      • if the interface_class is email. The value must be an valid email
      • if the interface_class is sms. The value must be an mobile phone number in E.164 format

    Contact Notification Send

    Example

    {
      "id": 523423,
      "sent_at": "2018-06-27T16:44:06.895Z",
      "contactmethod": {
        "id": 3231,
        "interface_class": "email",
        "value": "someone@email.com"
      }
    }
    
    • id

      integer

      The Contact Notification Send ID

    • sent_at

      string

      Datetime when it was sent using the Y-m-d\TH:i:s\Z format

    • contactmethod

      Contact Method Object

      The contact method

    Contact Notification Failed

    Example

    {
      "contactmethod": {
        "id": 86987,
        "interface_class": "email",
        "value": "email@email.com"
      }
    }
    
    • contactmethod

      Contact Method Object

      The contact method

    Metadata

    an object that contains variable keys and values based on the media.

    Media Download

    Example

    {
        "start": "2019-03-01T19:01:42.820412Z",
        "end": "2019-03-01T19:01:45.347410Z",
        "remote_addr": "",
        "total_bytes": 58774,
        "downloaded_bytes": 58774,
        "download_completed": 1,
        "created": "2019-03-01T19:01:42.820412Z",
        "updated": "2019-03-01T19:01:45.348411Z",   
    }
    
    • start

      string

      Datetime when the download was started using the Y-m-d\TH:i:s\Z format

    • end

      string

      Datetime when the download was ended using the Y-m-d\TH:i:s\Z format

    • remote_addr

      string

      The remote IP address

    • total_bytes

      integer

      Media Size

    • downloaded_bytes

      integer

      Media size downloaded

    • download_completed

      integer

      If the download was completed.

    • created

      string

      Datetime when it was created using the Y-m-d\TH:i:s\Z format

    • updated

      string

      Datetime when it was updated using the Y-m-d\TH:i:s\Z format

    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.

    timezones

    Developer Support

    Blog

    The Developer Blog features news and important announcements about the Botdoc API Platform. You will also find tutorials and best practices to help you build great platform integrations.

    Report Issue

    Help us help you!

    Always report any issue you find to api@botdoc.io

    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.

    Sample codes

    Botdoc provides a few sample codes to facilitate your development experience. If you would like us to make a sample code for any other programming language or endpoint, join us on Slack and let us know.

    Changelogs

    Each set of changelog describes changes that apply to the release:

    v1.0.17 - 05 April 2019

    v1.0.16 - 06 March 2019

    v1.0.15 - 22 January 2019

    v1.0.13 - 03 October 2018

    v1.0.12 - 06 September 2018

    v1.0.11 - 27 July 2018

    v1.0.10 - 20 June 2018

    v1.0.9 - 15 May 2018

    v1.0.8 - 26 April 2018

    v1.0.7 - 17 April 2018

    v1.0.6 - 30 March 2018

    v1.0.5 - 15 March 2018

    v1.0.4 - 27 February 2018

    v1.0.3 - 16 February 2018

    v1.0.2 - 01 February 2018

    v1.0.1 - 24 January 2018

    v1.0.0 - 15 January 2018