> 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

# Create request

POST https://api-d.docusign.com/v1/accounts/{accountId}/requests
Content-Type: application/json

Creates a new request from an intake form. Intake form field values are submitted separately.

Reference: https://developers.docusign.com/docs/agreement-desk-api/reference/agreementdesk/requests/createrequest

## Authentication

- `Authorization` header (bearer token, required) — Docusign OAuth 2.0 access token

## Servers

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

## Request

### Path parameters

- `accountId` (string, required) — The ID of the account that owns the request statuses.

### Body (application/json)

This endpoint expects a CreateRequestBody.

- `intake_form_id` (string, required) — The intake form to create the request from.
- `title` (string, required) — The title of the request.
- `due_date` (date, optional, nullable) — The date the request is due.
- `intake_form_fields` (CreateRequestBodyIntakeFormFields, optional, nullable) — Form field values, keyed by the field's API reference name (componentName, same value as the "id" returned by GET /request-types/{id}/fields). Submit a plain scalar per field, matching its field_type from the fields endpoint (string for Short Text/Text/Date/enum, number for Number and Currency — the currency code itself is fixed by the form and does not need to be supplied). A field with "read_only": true on the fields endpoint is rejected with a 400 error (code "read_only_field") if included. A Party (DynamicList) field also reports "read_only": true, but that reflects only its field type, not a form-author-configured read-only setting, so it can still be set — submit an array of objects, each with exactly one of "id" (an existing party's UUID) or "name" (a party display name — resolved to an existing party by exact match, or created if none matches), e.g. [{"id": "11111111-1111-1111-1111-111111111111"}, {"name": "Acme Corp"}]. If the form author has additionally configured a Party field as read-only, it is rejected like any other read-only field. A DynamicList field that isn't a Party lookup is rejected (code "unsupported_field_type"). An unrecognized field name is rejected (code "unknown_field"). For Attachment fields, upload the file to DMS yourself first, then submit an object of the form {"documentId": "<DMS document GUID>", "fileName": "Lease Agreement.docx"} as the field's value. A field omitted from intake_form_fields is set to the value the form author configured as its default, if any — including a read_only field, whose default is its value regardless of what the form's fields endpoint reports for other fields. A field present with an explicit null is left empty: no value is stored and no default is substituted; if that field is required, the request is rejected with a 400 error (code "invalid_value"). A default for a field hidden by the form's conditional display rules is not stored.
- `owner_id` (string, optional, nullable) — The owner of the request. Defaults to the submitter.
- `submitter_id` (string, optional, nullable) — The submitter of the request. Defaults to the authenticated user.

## Response

### 201

The request was created.

- `id` (string, required) — The unique identifier of the request.
- `intake_form_id` (string, required) — The identifier of the intake form the request was created from.
- `status` (string, required) — The current status of the request.
- `title` (string, required) — The title of the request.
- `_actions` (RequestActions, optional) — The set of actions available on a request.
- `_links` (RequestLinks, optional) — Hypermedia links for a request.
- `due_date` (date, optional, nullable) — The date the request is due.
- `friendly_id` (string, optional, nullable) — A human-readable identifier for the request (e.g. REQ-0042).
- `metadata` (ResourceMetadata, optional) — Audit and provenance metadata for a resource.
- `owner` (ParticipantSummary, optional) — A concise reference to a participant, such as the creator of a resource.
- `request_type_name` (string, optional, nullable) — The display name of the request type.
- `request_url` (string, optional, nullable) — Deep link to the request in the Agreement Desk UI.
- `submitter` (ParticipantSummary, optional) — A concise reference to a participant, such as the creator of a resource.

## Errors

### 400 Bad Request Error

The request was malformed.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 401 Unauthorized Error

The request was not authenticated.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 403 Forbidden Error

The caller is not permitted to create requests.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 422 Unprocessable Entity Error

No active intake form is available to create the request.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

## Types

### CreateRequestBodyIntakeFormFields

Form field values, keyed by the field's API reference name (componentName, same value as the "id" returned by GET /request-types/{id}/fields). Submit a plain scalar per field, matching its field_type from the fields endpoint (string for Short Text/Text/Date/enum, number for Number and Currency — the currency code itself is fixed by the form and does not need to be supplied). A field with "read_only": true on the fields endpoint is rejected with a 400 error (code "read_only_field") if included. A Party (DynamicList) field also reports "read_only": true, but that reflects only its field type, not a form-author-configured read-only setting, so it can still be set — submit an array of objects, each with exactly one of "id" (an existing party's UUID) or "name" (a party display name — resolved to an existing party by exact match, or created if none matches), e.g. [{"id": "11111111-1111-1111-1111-111111111111"}, {"name": "Acme Corp"}]. If the form author has additionally configured a Party field as read-only, it is rejected like any other read-only field. A DynamicList field that isn't a Party lookup is rejected (code "unsupported_field_type"). An unrecognized field name is rejected (code "unknown_field"). For Attachment fields, upload the file to DMS yourself first, then submit an object of the form {"documentId": "<DMS document GUID>", "fileName": "Lease Agreement.docx"} as the field's value. A field omitted from intake_form_fields is set to the value the form author configured as its default, if any — including a read_only field, whose default is its value regardless of what the form's fields endpoint reports for other fields. A field present with an explicit null is left empty: no value is stored and no default is substituted; if that field is required, the request is rejected with a 400 error (code "invalid_value"). A default for a field hidden by the form's conditional display rules is not stored.

### RequestActions

The set of actions available on a request.

- `add_document` (RequestAction, optional) — A hypermedia action (affordance) available on a request.
- `share` (RequestAction, optional) — A hypermedia action (affordance) available on a request.

### RequestLinks

Hypermedia links for a request.

- `collection` (PageLink, optional) — A URL that references a specific page in the pagination process.
- `self` (PageLink, optional) — A URL that references a specific page in the pagination process.
- `shares` (PageLink, optional) — A URL that references a specific page in the pagination process.

### ResourceMetadata

Audit and provenance metadata for a resource.

- `created_at` (datetime, optional, nullable) — Timestamp when the resource was created.
- `created_by` (string, optional, nullable) — User ID of the person who created the resource.
- `modified_at` (datetime, optional, nullable) — Timestamp when the resource was last modified.
- `modified_by` (string, optional, nullable) — User ID of the person who last modified the resource.

### ParticipantSummary

A concise reference to a participant, such as the creator of a resource.

- `participant_id` (string, required) — The unique identifier of the participant.
- `email` (string, optional, nullable) — The email address of the participant.
- `name` (string, optional, nullable) — The display name of the participant.

### 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.

### RequestAction

A hypermedia action (affordance) available on a request.

- `href` (string, required) — The target URL of the action.
- `method` (string, required) — The HTTP method to use for the action.
- `description` (string, optional, nullable) — A human-readable description of the action.

### PageLink

A URL that references a specific page in the pagination process.

- `href` (string, required) — The URL for the referenced page.

## Examples

### RequestCreated

**Response**

```json
{
  "id": "3f7c9e4b-851c-4f9b-89e7-123456789abc",
  "intake_form_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "Draft",
  "title": "Sample Agreement Request",
  "_actions": {
    "add_document": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc/documents",
      "method": "POST",
      "description": "Upload a document to this request"
    },
    "share": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc/shares/actions/add",
      "method": "POST",
      "description": "Share this request with additional principals"
    }
  },
  "_links": {
    "collection": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests"
    },
    "self": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc"
    },
    "shares": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc/shares"
    }
  },
  "due_date": "2025-02-15",
  "friendly_id": "REQ-0042",
  "metadata": {
    "created_at": "2026-08-26T14:30:00Z",
    "created_by": "bbbb2222-cccc-4ddd-8eee-ffff33334444",
    "modified_at": "2026-08-26T14:30:00Z",
    "modified_by": "bbbb2222-cccc-4ddd-8eee-ffff33334444"
  },
  "owner": {
    "participant_id": "aaaa1111-bbbb-4ccc-8ddd-eeee22223333",
    "email": "jamie.rivera@example.com",
    "name": "Jamie Rivera"
  },
  "request_type_name": "Standard NDA Intake",
  "request_url": "https://apps.docusign.com/agreements/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc",
  "submitter": {
    "participant_id": "bbbb2222-cccc-4ddd-8eee-ffff33334444",
    "email": "sam.alvarez@example.com",
    "name": "Sam Alvarez"
  }
}
```

### Create a request from an intake form

**Request**

```json
{
  "intake_form_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "Sample Agreement Request",
  "due_date": "2025-02-15",
  "intake_form_fields": {
    "AnnualValue": 5000,
    "RequestorEmail": "user@example.com",
    "StartDate": "2025-01-15"
  },
  "owner_id": "aaaa1111-bbbb-4ccc-8ddd-eeee22223333",
  "submitter_id": "bbbb2222-cccc-4ddd-8eee-ffff33334444"
}
```

**Response**

```json
{
  "id": "3f7c9e4b-851c-4f9b-89e7-123456789abc",
  "intake_form_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "Draft",
  "title": "Sample Agreement Request",
  "_actions": {
    "add_document": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc/documents",
      "method": "POST",
      "description": "Upload a document to this request"
    },
    "share": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc/shares/actions/add",
      "method": "POST",
      "description": "Share this request with additional principals"
    }
  },
  "_links": {
    "collection": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests"
    },
    "self": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc"
    },
    "shares": {
      "href": "https://api.docusign.com/v1/accounts/9f8e7d6c-1234-4a5b-8c9d-0e1f2a3b4c5d/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc/shares"
    }
  },
  "due_date": "2025-02-15",
  "friendly_id": "REQ-0042",
  "metadata": {
    "created_at": "2026-08-26T14:30:00Z",
    "created_by": "bbbb2222-cccc-4ddd-8eee-ffff33334444",
    "modified_at": "2026-08-26T14:30:00Z",
    "modified_by": "bbbb2222-cccc-4ddd-8eee-ffff33334444"
  },
  "owner": {
    "participant_id": "aaaa1111-bbbb-4ccc-8ddd-eeee22223333",
    "email": "jamie.rivera@example.com",
    "name": "Jamie Rivera"
  },
  "request_type_name": "Standard NDA Intake",
  "request_url": "https://apps.docusign.com/agreements/requests/3f7c9e4b-851c-4f9b-89e7-123456789abc",
  "submitter": {
    "participant_id": "bbbb2222-cccc-4ddd-8eee-ffff33334444",
    "email": "sam.alvarez@example.com",
    "name": "Sam Alvarez"
  }
}
```