API Reference

Download our OpenAPI specs

​

Healthcare APIs

We have drop-in replacements for the Change Healthcare (CHC) Eligibility, Professional Claims, and Claim Status APIs. These APIs allow you to directly switch from CHC to Stedi with minimal development effort.

​

EDI platform APIs

You can programmatically accomplish almost anything you can do in the Stedi app. In practice, most integrations only need to implement two integration points:

• A method in your system for calling the Create Outbound Transaction endpoint when you need to send a transaction to a trading partner
• A method in your system for receiving destination webhooks from Stedi when you receive a transaction from a trading partner, or when an exception occurs.

​

Authentication

You need an API key to use any Stedi API. You pass the API key in the Authorization header of every request and Stedi determines which resources you can access.

​

Creating an API key

To create an API key:

1. Log into your Stedi account.
2. Click your account name at the top right of the screen.
3. Select API Keys.
4. Click Generate API Key.
5. Enter a description and click Generate. Stedi generates an API key and allows you to copy it.

​

API key access

In accounts on an Essentials plan, an API key grants access to all resources belonging to an account.

In accounts on an Enterprise plan, members can be assigned to roles with different permissions. API keys inherit the permissions of the account member who created them and keep those permissions even if the creator’s role is later updated.

​

Passing the API key

Every request you send needs to include an API key. You pass the API key in the Authorization header. For example, if your API key is Jclcke.ZHqS3demo4dS16XZ1KeyBY7, you would insert it into the header according to the following example:

curl --request POST \
  --url https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi \
  --header 'Authorization: Jclcke.ZHqS3demo4dS16XZ1KeyBY7' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

​

Pagination

When you request a list of resources, the response may contain a subset of available responses. In that case, the response will include a key called next_page_token. To retrieve the next page of results, repeat the request, but add the query parameter page_token and give it the value you received in the response.

For example, when you call the List Transactions API, the result contains a list of every transaction within your Stedi account and a token for the next page.

{
  "items": [ ... ],
  "next_page_token": "2t7M75ZN1w4OnYFKKT0SUkT95w_ULzPR"
}

You can then request the next page of results like this:

  curl --request GET \
    --url https://core.us.stedi.com/2023-08-01/transactions?page_token=2t7M75ZN1w4OnYFKKT0SUkT95w_ULzPR \
    --header "Authorization: ${STEDI_API_KEY}"

As long as the response contains next_page_token, there are more results available. If a response doesn’t contain next_page_token, then you’re on the last page.

​

Error Responses

If you make a request that the API can’t fulfill, the response code will be in the 4xx range and the response body will contain the following two fields.

• error – A code indicating what went wrong.
• message – A human-readable message describing what went wrong.

You can use error to write code that handles the error and you can use message when you’re debugging the problem yourself. If a response needs to report multiple errors, it will include an array called errors, but even in that case, the error and message fields will be available at top level.

It’s possible for a response to contain both a result and an error. This happens when something went wrong, but the API is able to give a partial or best-effort result.

​

Idempotency keys

Idempotency allows you to make an API request multiple times without causing different outcomes. Adding idempotency keys to requests can prevent sending duplicate data to your trading partners in the case of network errors or other intermittent failures.

You can safely retry requests with the same idempotency key as many times as necessary within 24 hours after making the first request. Within the 24 hour period, if you reuse the same key with different request contents (change the HTTP method, path, or request body), Stedi returns a 422 Unprocessable Entity error. After 24 hours, Stedi allows the request to execute again even if you submit the same idempotency token.

​

Generating keys

For APIs that support idempotency, you can generate and include an idempotency key within the Idempotency-Key header of your request. Our implementation conforms to the draft IETF Idempotency-Key HTTP Header Field RFC.

The token can be any unique string, such as a UUID. Common approaches to generating tokens are:

• Use an algorithm that generates a token with enough randomness, like UUID v4.
• Derive the key from data related to the API call, like a partnership ID and a transaction number. This approach helps you prevent duplicate requests for the same partnership and request type.

​

Adding keys to your request

Once you have generated your idempotency key, include it in the header of your API request. For example, the header for a request to the Create Outbound Interchange API would look like this:

curl --request POST \
  --url https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi \
  --header 'Authorization: ${STEDI_API_KEY}' \
  --header 'Idempotency-Key: 5b6f6d3e-2c6d-4e6f-8e6f-6d3e2c6d4e6f' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

​

API upgrades

We strive to maintain backwards compatibility. The following changes are considered backwards compatible:

• New API resources
• Additional optional parameters to API requests
• Additional fields in API responses
• Changes in the order of properties in API responses
• Changes in human-readable error messages
• Downgrading mandatory parameters to optional parameters.

When we introduce a breaking change, we release a root-level, dated version.