Introduction

How to get started with the Xchain API

This guide will help you get started with the Xchain API service! All the important stuff – request parameters, example responses, possible response codes, etc – is documented here, but should you have any questions, always feel free to reach out to support@xchaintechnology.com.

Quick start

Get started with a test environment using your test API key. All test API requests are free and return fake data, and do not affect your live data or interact with ERP systems. The API key you use for authentication determines whether the request is in live or test mode.

  1. Retreieve your test API key on your dashboard API settings page. It will look something like sk_test_aed12HbPqeWXzcbvfT1zdp4y.
  2. Try listing your 3-way invoice matches with your test key:
    $ curl https://api.xchaintechnology.com/v1/matches\
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
      # The colon prevents curl from asking for a password.
  3. You should get a 200 response that looks something like this:
    [
      {
        "id": "ma_8TYhvTwcVF9tJc2gLfVqTdT4",
        "object": "match",
        "invoice": {
          "id": "in_qLnHAJ7hFDTbKW5XqfD6ktQB",
          "object": "invoice",
          ...
        },
        "po": {
          "id": "po_SzGFZneLuYGVwy8dSZZzZat4",
          "object": "po",
          ...
        },
        "receivable": {
          "id": "rc_qxPVveaPCd5KcHVhVjNHDt8v",
          "object": "receivable",
          ...
        },
        ...
      }
    ]

That's it! You've successfully completed a request to the Xchain API.

Authentication

The Xchain API uses alphanumeric keys to authenticate requests. You can manage your API keys in the Xchain Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. You can generate more restrictive API keys (than the default) for added security.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" instead of -u sk_test_4eC39HqLyjWDarjtT1zdp7dc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Xchain uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success. Codes in the 4xx range indicate an error given the information provided (ex: a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Xchain's servers, which rarely happen.

Some 4xx or 5xx errors that can be handled programmatically (ex: an invoice scan has failed) include an error code that briefly explains the error reported.

  • 200 - OK: Everything worked as expected
  • 400 - Bad Request: The request was unacceptable, often due to missing a required parameter
  • 401 - Unauthorized: No valid API key provided
  • 402 - Request Failed: The parameters were valid but the request failed
  • 403 - Forbidden: The API key doesn't have permissions to perform the request
  • 404 - Not Found: The requested resource doesn't exist
  • 409 - Conflict: The request conflicts with another request
  • 429 - Too Many Requests: Too many requests hit the API too quickly
  • 500, 502, 503, 504 - Server Errors: Something went wrong on Xchain's end (rare)
Jump to