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.

NOTE: These are the supported file types for the attachmentsUrl parameter: 'bib', 'bmp', 'dbf', 'dif', 'doc', 'docx', 'dotx', 'emf', 'eml', 'eps', 'epub', 'fodg', 'fodp', 'fods', 'fodt', 'gif', 'htm', 'html', 'jpeg', 'jpg', 'ltx', 'met', 'odd', 'odg', 'odp', 'ods', 'odt', 'otg', 'ots', 'ott', 'pbm', 'pct', 'pdb', 'pdf', 'pgm', 'png', 'pot', 'potm', 'ppm', 'pps', 'ppt', 'pptx', 'psw', 'pwp', 'pxl', 'ras', 'rtf', 'sda', 'sdc', 'sdd', 'sdw', 'slk', 'stc', 'std', 'sti', 'stw', 'svg', 'svm', 'swf', 'sxc', 'sxd', 'sxi', 'sxw', 'tif', 'tiff', 'txt', 'uop', 'uos', 'uot', 'vor', 'wmf', 'wps', 'xhtml', 'xls', 'xlsx', 'xlt', 'xltx', 'xml', 'xpm'

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