API contract: what it includes and how to write one

An application expects user_id in an API response. The provider changes it to userId, and the application stops finding the customer record. An API contract gives different systems a shared understanding of the fields and behavior they must support, so teams can identify breaking changes before production.

This guide explains the purpose of an API contract, shows REST and webhook examples, and walks through designing, testing, and maintaining a specification.

What is an API contract?

An API contract is a formal specification used in software development to describe how an application programming interface (API) provider and its consumers communicate. It identifies supported operations, the data a consumer must send, and the expected behavior of the API, including the responses the provider agrees to return.

The two parties have separate responsibilities:

• API provider: Exposes the endpoint and implements the documented behavior.
• API consumer: Calls the endpoint and handles its documented results.

For example, a customer system making a GET request to /v1/customers/42 needs to know whether the response includes user_id, name, and email, and what error to expect when customer 42 doesn't exist. If the provider changes user_id without preparing consumers, code that reads the original property can fail.

Here, contract describes a software interface, not necessarily a formal agreement between companies or a legally binding promise. API licensing terms, service-level agreements (SLAs), and data-processing agreements are separate. An eSignature API, for example, exposes signing operations, while the legal terms govern use of the service.

API contract vs. API documentation

An API contract specifies the operations and behavior an implementation must support. API contract documentation explains how developers configure and use those operations, including authentication, setup steps, and troubleshooting. These guides also help new developers understand an existing integration. The table shows where the two overlap and where they serve different purposes:

A machine-readable specification supports documentation generation, including API reference pages. Signeasy's API reference, for instance, exposes operations and examples, while the surrounding guides explain how the API works within a signing workflow. Neither a generated reference nor a written guide replaces implementation testing; the developer experience also depends on whether real calls behave as documented.

What should an API contract include?

An API contract should describe each operation closely enough that a consumer can build a request and handle both success and failure. For an HTTP API, the core elements are:

Not every operational rule fits into an API description language such as OpenAPI. Rate-limit policies, support commitments, and deprecation schedules sometimes need accompanying documentation. Security permissions also deserve precision to reduce the risk of unauthorized access and misuse of data. Signeasy's OAuth scope reference, for example, distinguishes permission to create a signature request (rs:create) from permission to generate a recipient signing link (rs:signingurl).

API contract examples: REST requests and webhooks

The following API contract examples use one signing scenario to show how a consistent API contract covers requests and completion events. An HR application sends an offer letter, receives a request identifier, and waits for a completion event before updating the candidate's record.

Example 1. REST API contract for a signature request

First, the HR application sends the document identifier and candidate email to an illustrative endpoint. The agreed behavior is POST /v1/signature-requests with a bearer token, returning 201 Created on success, 400 for invalid input, and 401 for unauthorized calls.

Illustrative request body:

{
  "document_id": "doc_1042",
  "signer_email": "alex@example.com"
}

Illustrative 201 Created response:

{
  "request_id": "req_872",
  "status": "pending"
}

The excerpt of an API contract below uses OpenAPI to specify those inputs, outputs, and errors in a format that documentation generators and contract-testing tools can parse.

openapi: 3.2.1
info:
  title: Example signature-request API
  version: 1.0.0
servers:
  - url: https://api.example.test
paths:
  /v1/signature-requests:
    post:
      operationId: createSignatureRequest
      summary: Create a signature request
      security:
        - bearerAuth: 
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [document_id, signer_email]
              properties:
                document_id:
                  type: string
                signer_email:
                  type: string
                  format: email
      responses:
        '201':
          description: Request created
          content:
            application/json:
              schema:
                type: object
                required: [request_id, status]
                properties:
                  request_id:
                    type: string
                  status:
                    type: string
                    enum: [pending]
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

The required arrays establish the expectations of the contract: what the provider must validate and what the consumer must supply. The request_id response property is also part of the agreement because the HR application stores it to identify the agreement later. If that field disappears, the consumer's status lookup needs updating.

This is a hypothetical endpoint. The live Signeasy envelope operation and its actual HTTP response codes appear in the product example below. The same distinction between structured inputs and document creation also applies to document automation APIs that populate agreements from application data.

Example 2. Webhook contract for a completed signature

The REST response confirms that the signing request was created, not that the candidate signed. The application needs to distinguish a created signing request from a completed agreement, so the HR system must receive a separate notification when all required recipients have signed. A webhook delivers that event to the application's own endpoint.

Illustrative completion payload:

{
  "event_id": "evt_3001",
  "event": "signature_request.completed",
  "request_id": "req_872",
  "completed_at": "2026-10-19T10:00:00Z"
}

To process the event safely, the webhook contract must answer these questions:

• Event and identifiers: Which event means fully completed, and which IDs link it to the original request and identify repeat deliveries?
• Payload and verification: Which properties are required, and how does the receiver authenticate the sender?
• Acknowledgment and retries: Which HTTP response confirms delivery, when does the provider retry, and what ordering guarantees apply?

For this example, the application uses request_id to retrieve the correct offer letter, checks whether event_id was already processed, and updates the candidate's record once. The payload and event name above are illustrative, not Signeasy's event schema.

Building signature requests and completion callbacks into an application? Review the relevant envelope operations and webhook events with our API team.

What API contract formats and standards are used?

The API contract should reflect the formats of data exchanged between systems. Some integrations need a combination of formats for HTTP requests and event notifications. The five options below cover HTTP, typed-service, and event-driven interfaces:

JSON Schema often describes a request or response body within a larger API specification, without tying that schema to a particular language. For HTTP APIs, OpenAPI is an established standard that documentation, mocking, and validation tools can use as a common definition. AsyncAPI describes asynchronous exchanges when event messages and channels require their own contract.

OpenAPI 3.2.1 is the current published specification. Before adopting a new version, check that the team's validator and code generator support it; some tools support only earlier releases.

Why do development teams use API contracts?

Development teams use API contracts for team collaboration before a complete service is ready and to check whether updates will affect existing applications. That provides four practical advantages:

1. Parallel development: Frontend and backend teams can use the same mock response while one builds the signing-status screen and the other implements the endpoint. Both use the same status values and ID fields.
2. Earlier error handling: A consumer checks how an invalid email or expired token appears in the error response before the integration goes live.
3. Repeatable integrations: Downstream teams using the same endpoint know which fields to send, which authorization scope to request, and how to handle missing data. Those choices are also covered in a broader eSign API integration guide.
4. Change reviews: When the provider proposes a different response schema, teams can compare it with the existing contract and run consumer tests before deploying it.

Good API contracts do not guarantee defect-free software. They make the expected behavior of your API reviewable and testable, so changes can be assessed before a consumer encounters them in production.

Planning an embedded signing workflow involving several application teams? See how Signeasy's documented requests and callbacks support the handoff between document creation and signing.

Contract-first vs. code-first API development

In contract-first API development, teams agree on the API design before implementing the interface. In code-first development, teams build the service first or alongside its specification, often generating OpenAPI descriptions from routes and models. This is a common practice in frameworks that expose route and type metadata.

The main differences are when the contract is established and how consumers are involved:

For a customer-facing signing portal, contract-first design lets the portal team and external API users agree on request IDs and completion statuses before the API is implemented. For an internal prototype with one developer, code-first avoids a separate design cycle. The first version of the specification still needs review against the implemented service.

Contract-first API development and code-first development both require ownership and validation. Defining the interface before implementation does not guarantee that the finished service follows it, while generating a specification from code does not establish that every error or permission rule has been documented. For an example of how the host application connects sending, signing, and events, see embedded eSignature experiences with Signeasy API.

How to write an API contract step by step

To write an API contract, start with a consumer operation and define the requests, responses, and failure behavior the provider will support. The following best practices help structure the first specification:

1. Identify what the consumer needs

Write down the action and the result the application expects before planning the implementation of your API. For an HR portal, that could be "send the offer letter and receive an ID we can use to track signing." If the letter is generated from employee data, define which fields need prefilling; Signeasy's merge-fields documentation shows an example of mapping labels to values.

2. Define endpoints and operations

Choose resource paths and HTTP methods based on those actions. Specify path and query parameters instead of leaving consumers to infer their use from examples.

3. Write request, response, and security schemas

Define required properties, types, success responses, and error objects. Record how callers authenticate and which permissions each action requires. Signeasy's authentication and authorization guide, for instance, distinguishes a single-account client-credentials flow from an authorization-code flow for applications connecting separate Signeasy accounts.

4. Select the specification format

For HTTP operations, write OpenAPI in YAML or JSON. If the system publishes messages, document their payloads and delivery rules separately or in an applicable event-driven specification.

5. Review and validate the contract

Have provider and consumer teams compare the proposed interface with their use cases to develop a clear understanding of required inputs, outputs, and failure cases. Use a specification validator such as Swagger Editor to catch structural errors, then check whether examples match the declared schemas.

6. Implement and test the interface

Create mock responses where consumers need to start early. Once the endpoint is implemented, use unit tests for local validation and contract tests for successful requests, bad inputs, missing permissions, and the fields consumed by the application.

7. Publish and maintain the specification

Store the current version of the API contract alongside its owner and change process. Update both contract and tests when behavior changes; document which old versions remain supported and when consumers must migrate.

Ready to map your signing requirements to real API endpoints? Our API team can review required recipient fields, permissions, and completion events.

How do you test and maintain an API contract?

API contract testing checks whether the implemented service satisfies its specification and the interactions consumers rely on. Maintenance adds the review and deprecation steps needed as those interactions change.

Validate requests and responses

Three testing methods answer different questions:

• Schema validation: Does a response include the required request_id and the correct data types?
• Provider contract testing: Does the actual endpoint return documented success and error responses when called with relevant inputs?
• Consumer-driven contract testing: Does the provider still support the requests and responses used by a particular application? Pact is one tool used to test these consumer-provider expectations.

API contract testing should run as part of the continuous integration process, alongside other CI/CD checks, before code is released. Schema checks establish whether responses follow the expected structure, while provider and consumer-driven tests examine actual interactions. Passing those checks does not prove that the full signing workflow functions correctly; functional and end-to-end testing are still required.

A failed contract test also needs a useful diagnostic trail. Each Signeasy API response includes an X-Signeasy-Request-Id header, described in the API request ID guidance, which developers can retain when investigating a failed call.

The same logs area also exposes webhook delivery statuses and error information. Those records help diagnose an integration after a failure; automated contract tests still determine whether the behavior matches the agreed interface.

Prevent breaking changes and contract drift

When an API changes, the review needs to distinguish additions that existing consumers are likely to tolerate from changes that require coordination. The following visual serves as a release-review reference in place of another workflow diagram.

For the opening user_id example, a provider should retain the old field during a transition or coordinate the userId change with consumers. If both names are accepted temporarily, document any data normalization needed to map them consistently. Version control and contract diffs expose the change; consumer tests show which applications still depend on the original name. Documentation must also say when deprecated behavior will stop working.

Need to examine how an existing signing integration handles webhook failures? Review delivery logs, retry behavior, and request IDs with a Signeasy API specialist.

What an API contract looks like in Signeasy's eSignature API

Signeasy's eSignature API provides a real example of how documented operations, security scopes, and event payloads fit into one integration. The relevant endpoint behavior is specific to Signeasy and is not interchangeable with the illustrative contract earlier.

Create an envelope and handle its response

The create or send an envelope reference documents POST https://api.signeasy.com/v3/rs/envelope/. Required inputs include embedded_signing, is_ordered, sources, and recipients. The reference lists 200 for a successful response and 400 or 422 for documented error conditions.

Here, an envelope represents a request containing documents and recipients. The consumer supplies the source documents and the recipients who should sign, then stores the returned request identifier for later actions. For an embedded workflow, the embedded signing guide covers generating a separate signing URL for each recipient. The host application must authenticate or verify its signer before presenting that URL.

Authenticate and process completion events

Signeasy authenticates API calls using OAuth access tokens. A single-account integration and a multi-account application follow different OAuth flows, and individual operations require the corresponding scopes. For example, rs:create is used to initiate requests, while rs:signingurl permits retrieval of embedded signing links.

Webhook event names distinguish intermediate activity from a completed agreement: rs.signed means one recipient signed; rs.completed means all required recipients finished. The webhook receiver must acknowledge delivery with HTTP 200 within 30 seconds. Events are asynchronous, with no guaranteed delivery order, and failed deliveries follow the documented retry policy over a 24-hour period.

For a customer portal, that distinction preserves the user experience by preventing the application from marking an agreement complete after only the first of several signers acts. It should wait for the completed event, then retrieve the signed document and update the correct customer record.

Apply the documentation to a production workflow

Bespoke Labs integrated Signeasy's API into its internal contractor-onboarding system. Its development team reported that the documentation was detailed enough to work independently, while webhooks synchronized signing status back to the platform. Bespoke Labs reports completing the signing-related onboarding batch for 50 to 60 experts in 3 to 4 minutes, compared with 5 to 8 hours of previous manual work per week.

Moreland University connected signing to its learning management system so completed enrollment agreements return to the relevant candidate records. These examples demonstrate application integrations, not evidence that either customer used a particular contract-first method or testing framework.

Our API pricing and production plans distinguish sandbox access from live signing capacity. If your organization only needs employees to send documents manually, Signeasy's eSignature software addresses that workflow without a custom API implementation.