Best Practice API Integrations

In this article, we will discuss best practices for integrating your system with ours via API.

Inbound Integration

• You will need to use webhooks in order to receive inbound faxes posted to your application
  • Each time a webhook event is triggered, it will automatically send a payload to a specified HTTPS endpoint provided and managed by you
• Webhooks can be set up in the portal or via API
• Webhooks can be set up on either the number level (each number's events will go to a different HTTPS endpoint), or on the account level (all events go to the same place)
• When a fax is received, the inbound webhook will fire with the payload containing all fax metadata
• Use the GET download fax endpoint and pass through the messageID that was received in each webhook payload 
  • This will download that specific fax as a PDF

Outbound Integration

• Generate an API key - each API key is attributed to a user
  • API keys can be generated in the web portal or via the API
    • Each API key has an access level (admin or user) - each endpoint on our API documentation has the needed access level 
    • In a multi-tenant environment, we recommend creating separate accounts for each client which can be found here
      • This will allow you to separate out each client for security, better reporting accuracy, and to keep fax history tied to each client respectively
      • API keys, users, fax numbers, and webhooks can be set independently for each account to best suit your integration
      • Reports can be generated for each of your client's accounts to accurately view usage independently
• POST Send fax endpoint is what you will use to send faxes
  • This contains all of the same options as the portal for sending a fax
    • Examples are adding a cover page, scheduling fax to go out at a later time, custom fields, tags, etc.
• POST Resend fax endpoint is another call that is commonly used
  • This allows you to resend a fax that previously failed by submitting the messageID of the previously failed fax
  • You can write a script utilizing this endpoint to automatically retry any failed faxes if they fail for a specific reason 
    • Retry reasons usually include fax number busy (6100) and fax transmit failed (8000)
• Set up an outbound fax webhook 
  • Outbound fax webhooks will provide the status of each sent fax and will notify you once a fax is either successful or a failure
  • The payload will look similar to the inbound fax webhook, only differences being the direction and the error codes 

Click here to access our API documentation.

If you have any other questions, please reach out to support@documo.com.