Appendix

Reference information for working with the Concord eVault API.

HTTP status codes

Error response format

All error responses follow the RFC 7807 Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Additional information about the error.",
  "traceId": "00-1234567890abcdef1234567890abcdef-1234567890abcdef-00"
}

Validation errors

Validation errors include an errors object with field-specific messages:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "name": ["The Name field is required."],
    "pageSize": ["The field pageSize must be between 1 and 100."]
  },
  "traceId": "00-1234567890abcdef1234567890abcdef-1234567890abcdef-00"
}

Rate limit error

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for this access key. Please retry after the specified time.",
  "retryAfterSeconds": 60
}

Pagination

List endpoints return paginated responses in one of two formats.

Standard format

{
  "data": [...],
  "metadata": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 150
  }
}

Legacy format

Some endpoints use this format:

{
  "items": [...],
  "totalCount": 150,
  "page": 1,
  "pageSize": 25
}

Response fields

Pagination parameters

Data types

GUID

Globally Unique Identifiers are used for all resource IDs. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6. Case-insensitive (lowercase recommended).

DateTime

All timestamps are in ISO 8601 format with UTC timezone. Format: YYYY-MM-DDTHH:mm:ss.sssZ. Example: 2024-01-15T10:30:00.000Z. Timezone is always UTC (indicated by the Z suffix).

File sizes

File sizes are returned in bytes as integers.

Enumerations

Package types

Package sources

Draft package status

Certified print status

Workflow status

Unmatched item reasons

Rate limiting

API requests are subject to rate limiting to ensure fair usage and protect the system.

Rate limits are applied per Access Key. Both limits must be satisfied for a request to succeed.

Rate limit response

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for this access key. Please retry after the specified time.",
  "retryAfterSeconds": 60
}

Rate limit headers

Handling rate limits

Best practices: implement exponential backoff when retrying failed requests; respect the Retry-After header (wait the specified time before retrying); cache responses when possible to reduce request volume; use pagination efficiently (larger page sizes mean fewer requests); batch operations (use bulk endpoints where available); and monitor your usage (track requests to avoid hitting limits).

API versioning

The Concord eVault API is currently at version 1.0. The API version is not included in the URL path.

Versioning strategy

Backward-compatible changes: New fields, new endpoints, and new optional parameters are added without version changes. Breaking changes: Major version increments for breaking changes (rare). Deprecation notice: Minimum 6-month notice before removing any endpoint or field.

Backward-compatible changes (no version bump)

The following changes are considered backward compatible: adding new API endpoints; adding new optional request parameters; adding new response fields; adding new enum values; changing the order of response fields; adding new HTTP headers.

What constitutes a breaking change

Removing an endpoint; removing a request parameter; removing a response field; changing the type of an existing field; changing the meaning of an existing field; renaming fields or endpoints.

Deprecation policy

Announcement: Deprecated features are announced via release notes and documentation. Warning period: Deprecated features continue to work for at least 6 months. Documentation: Deprecated features are marked in documentation with migration guidance. Removal: After the warning period, features may be removed in a major version.

Common MIME types

Note: The Draft Packages API only accepts PDF files (application/pdf).

Glossary

Support

Getting help

Reporting API issues

When reporting API issues, please include request information (full request URL without sensitive data, HTTP method, request headers excluding Authorization, request body if applicable), response information (HTTP status code, response body, the traceId from the error response), and context (what you were trying to accomplish, when the issue occurred, whether the issue is reproducible).

Example issue report

Subject: 500 Error on Package Search

Request:
POST /api/packages/search
Content-Type: application/json
{"query": "loan", "pageSize": 25}

Response:
HTTP 500
{
  "title": "Internal Server Error",
  "status": 500,
  "traceId": "00-abc123def456-789ghi012-00"
}

Context:
Searching for packages containing "loan" in the name.
Issue occurs consistently since 2024-01-15 10:00 UTC.

Quick reference

Authentication header

Authorization: Bearer vv_live_your_access_key_here

Common request headers

Base URL pattern

https://instance.evault.com/api/{endpoint}

Scope quick reference