> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Get bulk job status

GET https://api-d.docusign.com/v1/accounts/{accountId}/upload/jobs/{jobId}

Get the current status and details of a bulk job.

Reference: https://developers.docusign.com/docs/agreement-manager-api/reference/agreementmanager/bulkjob/getbulkjobstatus

## Authentication

- `Authorization` header (bearer token, required) — OAuth2 authentication. - Demo: - authorizationUrl: https://account-d.docusign.com/oauth/auth - tokenUrl: https://account-d.docusign.com/oauth/token - Production: - authorizationUrl: https://account.docusign.com/oauth/auth - tokenUrl: https://account.docusign.com/oauth/token

## Servers

- `https://api-d.docusign.com` (Demo server, default)
- `https://api.docusign.com` (Production server)

## Request

### Path parameters

- `accountId` (string, required)
- `jobId` (string, required)

### Query parameters

- `include_document_details` (boolean, optional, default: true) — When false, skips the per-document scan and returns aggregate counts in the summary field instead of _embedded.documents. Significantly improves response time for large jobs when only job status and high-level counts are needed.

## Response

### 200

The bulk job status and details

- `id` (string, required) — Id for job
- `name` (string, required) — User provided name for this job
- `status` (enum, required) — Job lifecycle states: - OPEN - Job created and accepting documents - UPLOAD_COMPLETE - All documents have been received, and processing has not yet started - IN_PROGRESS - Documents are being processed (AI extraction) - COMPLETE - The full e2e process is complete - FAILED - System error prevented job execution - CANCELED - User initiated request to cancel a job
  - Allowed values: `OPEN`, `UPLOAD_COMPLETE`, `IN_PROGRESS`, `COMPLETE`, `FAILED`, `CANCELED`
- `status_enum` (list of string, required)
- `created_at` (string, required)
- `modified_at` (string, required)
- `expires_at` (string, required)
- `metadata` (BulkJobMetadata, required) — Properties about THIS request/response, not the job resource itself
- `external_job_id` (string, optional) — User provided reference ID for this job
- `ttl_period` (string, optional) — ISO 8601 duration for job validity
- `upload_settings` (UploadSettings, optional) — Upload configuration settings for the bulk job
- `ai_processing` (AiProcessingStatus, optional) — AI processing status for BULK_API_INGESTION jobs. Always present; resume_ai_triggered_at is set only for jobs where resume-AI processing was triggered.
- `summary` (BulkJobSummary, optional) — Aggregate document counts. Always present in the job status response alongside _embedded.documents (when include_document_details=true) or as the sole count source (when false).
- `_embedded` (BulkJobEmbedded, optional) — Contains detailed information about the BulkJob including presigned upload links, document IDs, etc
- `_action_templates` (BulkJobActionTemplates, optional)
- `_links` (BulkJobLinks, optional)
- `constraints` (BulkJobConstraints, optional) — Describes the limits of a bulk job, or an action associated with a bulk job
- `message` (string, optional)

## Errors

### 401 Unauthorized Error

Unauthorized - Authentication is required

- `type` (string, required) — A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type. Use "about:blank" when no specific type documentation exists.
- `title` (string, required) — A short, human-readable summary of the problem type. Should not change between occurrences.
- `status` (integer, required) — The HTTP status code generated by the origin server for this occurrence of the problem.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `errors` (list of ValidationError, optional) — An array of detailed validation error objects when multiple issues exist. Each entry identifies a specific field-level or parameter-level error.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing and debugging with support.
- `timestamp` (string, optional) — The timestamp when the error occurred.

### 403 Forbidden Error

Forbidden - The user is not authorized to perform this operation

- `type` (string, required) — A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type. Use "about:blank" when no specific type documentation exists.
- `title` (string, required) — A short, human-readable summary of the problem type. Should not change between occurrences.
- `status` (integer, required) — The HTTP status code generated by the origin server for this occurrence of the problem.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `errors` (list of ValidationError, optional) — An array of detailed validation error objects when multiple issues exist. Each entry identifies a specific field-level or parameter-level error.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing and debugging with support.
- `timestamp` (string, optional) — The timestamp when the error occurred.

### 404 Not Found Error

Not Found - The requested resource was not found

- `type` (string, required) — A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type. Use "about:blank" when no specific type documentation exists.
- `title` (string, required) — A short, human-readable summary of the problem type. Should not change between occurrences.
- `status` (integer, required) — The HTTP status code generated by the origin server for this occurrence of the problem.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `errors` (list of ValidationError, optional) — An array of detailed validation error objects when multiple issues exist. Each entry identifies a specific field-level or parameter-level error.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing and debugging with support.
- `timestamp` (string, optional) — The timestamp when the error occurred.

### 500 Internal Server Error

Internal Server Error - An unexpected error occurred

- `type` (string, required) — A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type. Use "about:blank" when no specific type documentation exists.
- `title` (string, required) — A short, human-readable summary of the problem type. Should not change between occurrences.
- `status` (integer, required) — The HTTP status code generated by the origin server for this occurrence of the problem.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `errors` (list of ValidationError, optional) — An array of detailed validation error objects when multiple issues exist. Each entry identifies a specific field-level or parameter-level error.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing and debugging with support.
- `timestamp` (string, optional) — The timestamp when the error occurred.

## Types

### BulkJobMetadata

Properties about THIS request/response, not the job resource itself

- `request_id` (string, optional)
- `response_timestamp` (string, optional) — When this response was generated
- `response_duration` (integer, optional) — Time in ms to process this request

### UploadSettings

Upload configuration settings for the bulk job

- `ai_extraction` (boolean, optional, default: true) — Controls AI extraction behavior for all documents in the job. - If set to false, AI processing is skipped for all documents in the job - If set to true or not provided (defaults to true), AI processing behavior is determined per document based on file type and size

### AiProcessingStatus

AI processing status for BULK_API_INGESTION jobs. Always present; resume_ai_triggered_at is set only for jobs where resume-AI processing was triggered.

- `resume_ai_triggered_at` (string, optional) — When resume-AI processing was triggered
- `processed` (integer, optional) — Number of documents that successfully completed AI processing
- `skipped` (integer, optional) — Number of documents where AI processing was skipped (file too large, unsupported format, or job-level opt-out)
- `in_progress` (integer, optional) — Number of documents currently being processed
- `failed` (integer, optional) — Number of documents that failed at any processing step

### BulkJobSummary

Aggregate document counts. Always present in the job status response alongside _embedded.documents (when include_document_details=true) or as the sole count source (when false).

- `total` (integer, optional) — Total number of documents in the job
- `agreements_created` (integer, optional) — Documents that successfully completed agreement creation (UPLOAD_TO_EMS/SUCCEEDED)
- `failed` (integer, optional) — Total documents that failed at any processing step
- `canceled` (integer, optional) — Total documents that were canceled
- `in_progress` (integer, optional) — Total documents still being processed (not yet in a terminal state)

### BulkJobEmbedded

Contains detailed information about the BulkJob including presigned upload links, document IDs, etc

- `document_status_enum` (list of string, optional) — All possible document status values
- `documents` (list of BulkJobEmbeddedItems, optional) — List of documents with presigned upload URLs
- `duplicate_count` (integer, optional) — Total number of documents flagged as duplicates in this job (may increase as checks complete). Omitted from the response when no deduplication results are available yet (no document has been checked).

### BulkJobActionTemplates

- `upload_document` (BulkJobActionTemplate, optional)

### BulkJobLinks

- `self` (string, optional)

### BulkJobConstraints

Describes the limits of a bulk job, or an action associated with a bulk job

- `max_size_mb` (integer, optional)
- `max_documents_per_job` (integer, optional)
- `allowed_formats` (list of string, optional)
- `timeout_seconds` (integer, optional)

### ValidationError

A single field-level or parameter-level validation error.

- `code` (string, required) — A machine-readable error code identifying the specific validation failure.
- `message` (string, required) — A human-readable description of the validation error.
- `target` (string, optional) — The name of the field, parameter, or path segment that caused the error.

### BulkJobEmbeddedItems

- `id` (string, optional) — Id of the document
- `agreement_id` (string, optional) — Agreement ID associated with this document, if created
- `sequence` (integer, optional) — Sequential order of the document
- `status` (enum, optional) — Document status. Last 4 are terminal statuses. Matches enum with similar name in the backend.
  - Allowed values: `NOT_STARTED`, `IN_PROGRESS`, `CANCELED`, `SUCCEEDED`, `SUCCEEDED_WITH_WARNINGS`, `FAILED`
- `file_name` (string, optional) — The name of the uploaded file
- `ai_extraction` (boolean, optional) — Whether AI extraction was performed on this document
- `error_code` (integer, optional) — Error code if document processing failed
- `error` (string, optional) — Error message if document processing failed
- `warnings` (list of DocumentWarning, optional) — List of warnings encountered during document processing. Present when status is SUCCEEDED_WITH_WARNINGS.
- `is_duplicate` (boolean, optional) — Whether this document was identified as a duplicate (exact or partial match). `true` when a duplicate; `false` when checked and not a duplicate. Omitted from the response when deduplication has not yet completed for this document.
- `_actions` (BulkJobItemActions, optional) — Available actions for this document. Actions vary based on document state - upload actions during initial upload, remediation actions after processing.
- `_links` (BulkJobEmbeddedItemsLinks, optional) — Hypermedia links related to this document

### BulkJobActionTemplate

- `method` (string, optional) — HTTP method used for this template
- `required` (boolean, optional) — Whether this action is required
- `description` (string, optional)
- `template_variables` (BulkJobActionTemplateTemplateVariables, optional) — Key value pairs of variable names and descriptions, explaining how they are to be used
- `headers` (BulkJobActionTemplateHeaders, optional) — Key value pairs of header names and example values
- `constraints` (BulkJobConstraints, optional) — Describes the limits of a bulk job, or an action associated with a bulk job
- `success_status_code` (integer, optional)
- `error_status_codes` (BulkJobActionTemplateErrorStatusCodes, optional) — Key value pairs of error response codes and explanations of those codes

### DocumentWarning

A warning encountered during document processing that did not prevent overall success.

- `code` (string, required) — Machine-readable warning code
- `message` (string, required) — Human-readable warning summary
- `recoverable` (boolean, required) — Whether this warning can be remediated by the client
- `detail` (string, optional) — Detailed diagnostic information about the warning
- `remedy` (string, optional) — Key referencing an action in `_actions` that can resolve this warning

### BulkJobItemActions

Available actions for this document. Actions vary based on document state - upload actions during initial upload, remediation actions after processing.

- `upload_document` (string, optional) — Azure Blob Store presigned URL to upload the document file (valid for ~8 hours)
- `update_metadata` (Affordance, optional) — Affordances (aka 'actions') describe the available operations on a resource, including CRUD and RPC-like operations. It details the expected input payload, http method, query parameters, and the resulting output. Affordances enable clients to dynamically adapt to the API's current state and available actions. Instead of hardcoding all possible endpoints and their associated logic, a client can inspect the affordances within a resource's representation to discover what actions are possible and how to perform them.

### BulkJobEmbeddedItemsLinks

Hypermedia links related to this document

- `document` (BulkJobEmbeddedItemsLinksDocument, optional) — Link to download the document
- `agreement` (BulkJobEmbeddedItemsLinksAgreement, optional) — Link to the associated agreement

### BulkJobActionTemplateTemplateVariables

Key value pairs of variable names and descriptions, explaining how they are to be used

### BulkJobActionTemplateHeaders

Key value pairs of header names and example values

### BulkJobActionTemplateErrorStatusCodes

Key value pairs of error response codes and explanations of those codes

### Affordance

Affordances (aka 'actions') describe the available operations on a resource, including CRUD and RPC-like operations. It details the expected input payload, http method, query parameters, and the resulting output. Affordances enable clients to dynamically adapt to the API's current state and available actions. Instead of hardcoding all possible endpoints and their associated logic, a client can inspect the affordances within a resource's representation to discover what actions are possible and how to perform them.

- `href` (string, optional) — A URI representing the location of the resource or operations.
- `method` (enum, optional) — The http method to use when invoking this affordance
  - Allowed values: `POST`, `GET`, `PATCH`, `PUT`, `DELETE`
- `required` (boolean, optional, default: false) — Indicates if an action must be performed on a resource. This may include a manadatory step as part of a business process, especially when failing to execute a subsequent action will leave the resource in a bad or incomplete state. # note: would it be necessary for manadatory/required actionsto be performed prior to an optional action # note: mandatory actions which have previously been executed on a resource should not be be returned in the server response # execept in cases where the resource is in a state that permits this action to be performed again.
- `sequence` (integer, optional) — Provides a stable and consistent order to a collection of resources. Useful when multiple processes are working in parallel to iterate over a collection of resources with a mandatory/required action.
- `description` (string, optional) — Placeholder
- `template_variables` (map from string to string, optional) — A natural language dictionary of JSON template variables used in invoke an action
- `headers` (map from string to string, optional) — Additional HTTP request headers needed in the request to invoke an action.
- `constraints` (any, optional) — Limits and restrictions on
- `success_status_code` (integer, optional) — Success status codes (2xx range) indicating the request was received, understood, and accepted. Common codes: - 200: OK - Standard successful response - 201: Created - Resource successfully created - 202: Accepted - Request accepted for processing - 204: No Content - Successful with no response body - 206: Partial Content - Partial resource returned

### BulkJobEmbeddedItemsLinksDocument

Link to download the document

- `href` (string, optional) — URL to download the document

### BulkJobEmbeddedItemsLinksAgreement

Link to the associated agreement

- `href` (string, optional) — URL to the agreement resource

## Examples

**Response**

```json
{
  "id": "1892e0d1-95c8-4ccd-86b6-705822482bf9",
  "name": "test_name_with_sets_offsite",
  "status": "COMPLETE",
  "status_enum": [
    "OPEN",
    "UPLOAD_COMPLETE",
    "IN_PROGRESS",
    "COMPLETE",
    "FAILED",
    "CANCELED"
  ],
  "created_at": "2025-12-05T20:34:40.529136Z",
  "modified_at": "2025-12-05T20:34:55.677612Z",
  "expires_at": "2025-12-08T20:34:40.529136Z",
  "metadata": {
    "response_timestamp": "2025-12-10T20:43:06.725436506Z",
    "response_duration": 5
  },
  "ttl_period": "P3D",
  "_embedded": {
    "document_status_enum": [
      "NOT_STARTED",
      "IN_PROGRESS",
      "CANCELED",
      "SUCCEEDED",
      "SUCCEEDED_WITH_WARNINGS",
      "FAILED"
    ],
    "documents": [
      {
        "id": "c972fc7c-9abf-4074-bd17-6b0a1a3f103a",
        "status": "FAILED",
        "error_code": 6105,
        "error": "File was not uploaded"
      },
      {
        "id": "60778f49-be9a-48af-a5c8-ce2efc57ab0f",
        "agreement_id": "e4c999b7-bdbd-42a1-99eb-c7569b65d7e7",
        "status": "SUCCEEDED",
        "file_name": "filename.pdf",
        "ai_extraction": true,
        "_links": {
          "document": {
            "href": "https://s1.us.services.demo.docusign.net/document-public-dms/v1/accounts/{accountId}/documents/{documentId}"
          },
          "agreement": {
            "href": "/v1/accounts/{accountId}/agreements/e4c999b7-bdbd-42a1-99eb-c7569b65d7e7"
          }
        }
      },
      {
        "id": "8d9e2654-62ac-40bd-9f34-76424ee8e968",
        "agreement_id": "09ecfcd6-783b-410b-a368-1e4e43fb1c17",
        "status": "SUCCEEDED_WITH_WARNINGS",
        "file_name": "1738567852650_Travelers Auto WC Binder.pdf",
        "ai_extraction": true,
        "warnings": [
          {
            "code": "METADATA_APPLICATION_FAILED",
            "message": "Applying metadata failed",
            "recoverable": true,
            "detail": "Data validation failed. $class may contain an incompatible value.",
            "remedy": "update_metadata"
          }
        ],
        "_actions": {
          "update_metadata": {
            "href": "/v1/accounts/{accountId}/agreements/09ecfcd6-783b-410b-a368-1e4e43fb1c17",
            "method": "PATCH",
            "description": "Submit metadata for this agreement with valid payload"
          }
        },
        "_links": {
          "document": {
            "href": "https://s1.us.services.demo.docusign.net/document-public-dms/v1/accounts/{accountId}/documents/8d9e2654-62ac-40bd-9f34-76424ee8e968"
          },
          "agreement": {
            "href": "/v1/accounts/{accountId}/agreements/09ecfcd6-783b-410b-a368-1e4e43fb1c17"
          }
        }
      }
    ]
  }
}
```