Conventions

Shared conventions that apply across all External API endpoints.

Content type

All requests and responses are JSON (application/json). The API does not accept or produce XML, form-encoded bodies on read endpoints, or any other content type.

The one exception is the OAuth2 token endpoint itself, which follows the OAuth2 standard and accepts application/x-www-form-urlencoded. See Authentication.

Response envelope

Successful responses wrap their payload in a data field.

Single resource:

{ "data": { "id": "123", "name": "..." } }

List resource:

{ "data": [ { ... }, { ... } ] }

This envelope is consistent regardless of endpoint. The shape inside data varies per endpoint — see the Supplier API reference for specifics.

Error envelope

Errors use a separate shape with an _errors array:

{
  "_errors": [
    {
      "code": "CLIENT_ID_HEADER_MISSING",
      "detail": "Missing required x-e1-client-id header"
    }
  ]
}

Validation errors may additionally include a source.parameter to point at the offending field:

{
  "_errors": [
    {
      "code": "INVALID_PARAMETER",
      "detail": "companyId must be a numeric string",
      "source": { "parameter": "companyId" }
    }
  ]
}

The full list of error codes lives in Errors.

Dates and times

The Supplier API exclusively uses dates (no time component) on response fields (tenderOpenAt, quotesDueAt), formatted as ISO 8601 YYYY-MM-DD, e.g. 2026-04-06.

Date fields may be null when not set (e.g. a tender with no due date). Future endpoints that return full timestamps will use ISO 8601 with UTC offset (e.g. 2026-05-15T00:00:00+00:00); none are exposed today.

Identifiers

• Identifiers are strings, even when they look numeric. Don’t assume parseInt is safe — treat IDs as opaque tokens.
• companyId values are assigned by E1 and stable across the lifetime of the company.

Pagination

The Supplier API does not paginate. Each response returns the full set of currently-open matched projects. Cardinality is bounded naturally by the number of open tenders that match the assigned user’s keywords; the endpoint takes no windowing parameter, so there is no client-side knob for narrowing the response.

HTTP status codes

Status	Meaning
200 OK	Request succeeded. Body contains the data envelope.
400 Bad Request	The request was malformed — missing required header, invalid parameter, etc.
401 Unauthorised	Authentication or authorization failed. See Errors.
403 Forbidden	The supplier company you are calling for is not licensed for this endpoint. See Errors.
429 Too Many Requests	Rate limit exceeded for your (token, x-e1-client-id) bucket. See Rate limits.
5xx	Something broke on our side. Retry with exponential backoff; escalate if it persists.

Note that the API will sometimes return 200 OK with an empty data: [] — that is not an error. It means your query ran successfully but there were no matching projects. See Data freshness for why that might be.