Skip to main content

Unveiling the World of our API Responses

Step into the arena where data meets design - our API responses are crafted to be both intuitive and insightful. Let's explore!


Our Common Format: The Backbone​

Every response from our API adheres to a consistent structure, ensuring you always know what to expect:

Common data format
{
  "version": "1.0",
  "resource_type": "<the resource type here>",
  "data": { ... }
}
  • version – Indicates the version of the response format. While not strict Semantic Versioning (SemVer), it reflects whether the change is breaking or additive.
  • resource_type – Identifies the type of resource returned (e.g. agreement, participant, etc.).
  • data – Contains the primary payload of the response.

Supported Response Types​


Single Resource​

A single object representing the requested resource.

Single resource
{
  "version": "1.0",
  "resource_type": "<resource_type>",
  "result_type": "single",
  "data": { ... }
}

List Resource​

An array of resource objects, without pagination.

The list resource
{
  "version": "1.0",
  "resource_type": "<resource_type>",
  "result_type": "list",
  "data": [ ... ]
}

Paginated List​

A list of resources returned in pages, including metadata for pagination.

The paginated list resource
{
  "version": "1.0",
  "resource_type": "<resource_type>",
  "result_type": "paginated_list",
  "pagination": {
    "limit": 25,
    "page": 1,
    "total_results": 250,
    "total_pages": 10
  },
  "data": [ ... ]
}

Deleted Resource​

Confirms that a resource has been deleted. The data field contains a snapshot of the deleted object.

The delete resource
{
  "version": "1.0",
  "resource_type": "<resource_type>",
  "result_type": "deleted",
  "data": { ... }
}

Webhook Event​

Delivered asynchronously when something important happens. Includes event metadata and the resource payload.

The webhook event resource
{
  "version": "1.0",
  "resource_type": "<resource_type>",
  "event": "<event_name>",
  "request_timestamp": "<ISO 8601 timestamp>",
  "data": { ... }
}

Versioning and Compatibility​

Zigned uses a pragmatic approach to response versioning:

  • Major changes introduce a new version value in the response payload.
  • Additive changes (such as new fields or nested objects) are made within the same version and do not break existing integrations.
  • No silent removals – once a key is introduced in a version, it will not be removed or renamed within that same major version.

To maintain compatibility across changes:

  • Your client should ignore unknown fields in the response.
  • Monitor the version field to detect changes that may require review.
  • Refer to the changelog for a detailed history of updates.

Summary​

The Zigned API response format is designed for consistency, predictability, and long-term maintainability. Whether you're consuming a single resource or building a complex signing flow, the structured format ensures your integration stays clean and robust.