### Proof of Address Example - JSON

Source: https://developers.yousign.com/reference/post-verifications-proofs_of_address

This example demonstrates the structure of a Proof of Address object when a verification is pending. It includes identifiers, timestamps, status, and an empty data field for extracted information.

```json
{
  "id": "1b671a64-40d5-491e-99b0-da01ff1f3341",
  "workspace_id": "9412b83b-b4b9-4a94-97b5-2b43dfa4cde3",
  "workflow_session_id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
  "previous_attempt_id": "9412b83b-b4b9-4a94-97b5-2b43dfa4cde4",
  "applicant_id": null,
  "created_at": "2023-01-01T12:00:00+00:00",
  "updated_at": "2023-01-01T12:00:00+00:00",
  "status": "pending",
  "status_codes": [],
  "data_anonymized": false,
  "data": {
    "extracted_from_document": {
      "first_name": null,
      "last_name": null,
      "full_address": null,
      "issued_on": null,
      "2d_doc": {
        "full_name": null,
        "address": {
          "line1": null,
          "postal_code": null,
          "city": null,
          "country_code": null
        }
      }
    }
  }
}
```

--------------------------------

### Business Registration Certificate JSON Example

Source: https://developers.yousign.com/reference/approver-notified

An example JSON object representing the extracted data from a business registration certificate. It includes company status, legal form, branch address, and identification numbers.

```json
{
  "issuance_date": "2025-01-01",
  "company_description": {
    "active": true,
    "legal_form": "Entreprise individuelle",
    "company_name": null,
    "company_number": "123 4567 890",
    "headquarter_company_number": "123 4567 890 12345",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe"
  },
  "branch_description": {
    "active": true,
    "branch_company_number": "123 4567 890 12345",
    "address": "1 rue de la paix, 75000 Paris",
    "city": "Paris",
    "postal_code": "75000"
  },
  "document_type": "Avis de situation"
}
```

--------------------------------

### GET /custom-experiences

Source: https://developers.yousign.com/reference/get-custom_experiences-customexperienceid-1

Retrieves the details of a specific custom experience configuration.

```APIDOC
## GET /custom-experiences

### Description
Retrieves the configuration details for a custom experience, including colors, disabled UI elements, and notification settings.

### Method
GET

### Endpoint
/custom-experiences

### Parameters
None

### Request Example
GET /custom-experiences

### Response
#### Success Response (200)
- **id** (UUID) - The unique identifier for the custom experience.
- **name** (string) - The name of the custom experience.
- **landing_page_disabled** (boolean) - Whether the landing page is disabled.
- **background_color** (string) - The hex code for the background color.

#### Response Example
{
  "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
  "name": "Corporate Branding",
  "landing_page_disabled": false,
  "background_color": "#FFFFFF"
}
```

--------------------------------

### GET /workspaces

Source: https://developers.yousign.com/reference/get-workspaces-1

Retrieve a paginated list of all workspaces within your Yousign organization.

```APIDOC
## GET /workspaces

### Description
Returns the list of all Workspaces within your Organization. This endpoint supports pagination using cursor-based parameters.

### Method
GET

### Endpoint
/workspaces

### Parameters
#### Query Parameters
- **after** (string) - Optional - After cursor (pagination)
- **limit** (integer) - Optional - The limit of items count to retrieve (default: 10, max: 100)

### Request Example
GET /workspaces?limit=10

### Response
#### Success Response (200)
- **data** (array) - List of workspace objects

#### Response Example
{
  "data": [
    {
      "id": "ws_12345",
      "name": "Marketing Workspace"
    }
  ]
}
```

--------------------------------

### GET /auto-insurance-claims-history

Source: https://developers.yousign.com/reference/signature_request-reactivated

Retrieves the schema and example data structure for extracted auto insurance claims history documents.

```APIDOC
## GET /auto-insurance-claims-history

### Description
Returns the data structure for extracted auto insurance claims history, including policy holder details, vehicle information, driver history, and incident reports.

### Method
GET

### Endpoint
/auto-insurance-claims-history

### Parameters
#### Path Parameters
None

### Response
#### Success Response (200)
- **policy_holder_full_name** (string) - Full name of the policy holder
- **insurance_score** (string) - Calculated insurance score
- **drivers_information** (array) - List of drivers associated with the policy
- **incidents_information** (array) - List of reported incidents

#### Response Example
{
  "policy_holder_full_name": "John Doe",
  "insurance_score": "0.50",
  "vehicle_model": "Renault Clio",
  "drivers_information": [
    {
      "driver_full_name": "John Doe",
      "driver_license_number": "12345678"
    }
  ],
  "incidents_information": []
}
```

--------------------------------

### Example API Endpoint

Source: https://developers.yousign.com/reference/upload-an-electronic-seal-document

This snippet demonstrates a sample API endpoint with request and response examples.

```APIDOC
## GET /example/endpoint

### Description
This endpoint retrieves example data.

### Method
GET

### Endpoint
/example/endpoint

### Parameters
#### Query Parameters
- **id** (string) - Required - The identifier for the data.

### Request Example
```json
{
  "message": "This is a sample request."
}
```

### Response
#### Success Response (200)
- **type** (string) - The type of the returned data.
- **detail** (string) - A detailed description of the data.

#### Response Example
```json
{
  "type": "success",
  "detail": "Data retrieved successfully."
}
```
```

--------------------------------

### POST /companies/initiate-from-file

Source: https://developers.yousign.com/reference/post-verifications-companies

Initiates a company verification process by uploading an official company document (e.g., Kbis).

```APIDOC
## POST /companies/initiate-from-file

### Description
Initiates a company verification process by uploading an official company document, such as a Kbis file.

### Method
POST

### Endpoint
/companies/initiate-from-file

### Parameters
#### Request Body
- **file** (binary) - Required - The company document file (PDF, max 10MB).
- **country_code** (string) - Required - The country code (currently supports FR).
- **workspace_id** (string) - Optional - UUID of the workspace.

### Request Example
{
  "file": "[Binary File]",
  "country_code": "FR"
}
```

--------------------------------

### POST /workspaces

Source: https://developers.yousign.com/reference/post-workspace-1

Create a new workspace within your Yousign organization to partition entities.

```APIDOC
## POST /workspaces

### Description
Creates a new Workspace in the organization. This allows you to partition your Yousign organization into separate entities.

### Method
POST

### Endpoint
/workspaces

### Parameters
#### Request Body
- **name** (string) - Required - The name of the workspace to be created.

### Request Example
{
  "name": "My New Workspace"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created workspace.
- **name** (string) - The name of the workspace.

#### Response Example
{
  "id": "ws_12345",
  "name": "My New Workspace"
}
```

--------------------------------

### Workflow Session Started Event

Source: https://developers.yousign.com/reference/verification-bank_account_connection-done

Details the structure of the 'workflow_session.started' webhook event, providing information about the newly started workflow session.

```APIDOC
## Webhook Event: workflow_session.started

### Description
This event is triggered when a new workflow session is initiated.

### Method
POST

### Endpoint
`/webhooks`

### Request Body
- **event_name** (string) - Required - The name of the event, which is 'workflow_session.started'.
- **data** (object) - Required - Contains detailed information about the Workflow Session that triggered this event.
  - **workflow_session** (object) - Required - Workflow Session that triggered the webhook event.
    - **id** (string) - Required - Unique identifier of the Workflow Session.
    - **name** (string) - Required - Name given to the Workflow Session.
    - **status** (string) - Required - The current status of the Workflow Session.
    - **action_groups** (array) - Required - List of the Action Groups contained in the Workflow Session.
      - **type** (string) - Required - The type of the Action Group.
      - **status** (string) - Required - The status of the Action Group.

### Request Example
```json
{
  "event_name": "workflow_session.started",
  "data": {
    "workflow_session": {
      "id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
      "name": "Customer onboarding of John Doe",
      "status": "in_progress",
      "action_groups": [
        {
          "type": "signature",
          "status": "pending"
        }
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Webhook received successfully"
}
```
```

--------------------------------

### POST /identity-video/initiate

Source: https://developers.yousign.com/reference/post-verifications-identity_videos

Initiates a new identity video verification session for a user.

```APIDOC
## POST /identity-video/initiate

### Description
Initiates a new identity video verification flow. Requires user's name as it appears on their ID document and a redirection URL.

### Method
POST

### Endpoint
/identity-video/initiate

### Parameters
#### Request Body
- **first_name** (string) - Required - First name matching the ID document.
- **last_name** (string) - Required - Last name matching the ID document.
- **redirection_url** (string) - Required - URL to redirect after verification.
- **face_recognition** (boolean) - Optional - Enable face recognition.
- **pvid** (boolean) - Optional - Enable PVID mode.
- **workspace_id** (string) - Optional - Workspace UUID.

### Request Example
{
  "first_name": "John",
  "last_name": "Doe",
  "redirection_url": "https://example.com/",
  "face_recognition": false
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the verification session.

#### Response Example
{
  "id": "9412b83b-b4b9-4a94-97b5-2b43dfa4cde3"
}
```

--------------------------------

### Workflow Session Started Event

Source: https://developers.yousign.com/reference/signature_request-permanently_deleted

Details the structure of the 'workflow_session.started' webhook event, including the metadata and the data payload containing information about the newly started workflow session.

```APIDOC
## Workflow Session Started Event

### Description
This event is triggered when a new workflow session is initiated. It provides details about the workflow session, such as its ID, name, status, and the action groups it contains.

### Event Name
`workflow_session.started`

### Data Payload

#### `workflow_session` Object
- **id** (string, uuid) - Unique identifier of the Workflow Session.
- **name** (string) - Name given to the Workflow Session.
- **status** (WorkflowSessionStatus) - The current status of the workflow session.
- **action_groups** (array) - List of Action Groups within the Workflow Session.
  - Each item in the array is an object with:
    - **type** (ActionGroupType) - The type of the action group.
    - **status** (ActionGroupStatus) - The status of the action group.

### Response Example
```json
{
  "event_name": "workflow_session.started",
  "data": {
    "workflow_session": {
      "id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
      "name": "Customer onboarding of John Doe",
      "status": "pending",
      "action_groups": [
        {
          "type": "signature",
          "status": "pending"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Define Auto Insurance Claims History Example

Source: https://developers.yousign.com/reference/post-document_analyses

This JSON object provides an example structure for auto insurance claims history data, including policy holder information.

```json
{
  "policy_holder_full_name": "John Doe",
  "policy_holder_address": "1 rue de la Paix, 75001 Paris"
}
```

--------------------------------

### POST /bank-account-lookups/from-file

Source: https://developers.yousign.com/reference/post-verifications-bank_account_lookups

Initiate a new bank account lookup verification by uploading a file containing the IBAN.

```APIDOC
## POST /bank-account-lookups/from-file

### Description
Initiate a new Bank Account Lookup Verification by providing a file (PDF) containing the IBAN.

### Method
POST

### Endpoint
/bank-account-lookups/from-file

### Parameters
#### Request Body
- **file** (binary) - Required - The file containing the IBAN number (PDF, max 10MB).
- **natural_person** (object) - Required - The natural person details.

### Request Example
{
  "file": "Binary file content",
  "natural_person": {}
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the verification.
```

--------------------------------

### Get Consumption Detail Response Schema

Source: https://developers.yousign.com/reference/get-consumption-detail-1

Defines the structure for the successful response of the 'get consumption detail' endpoint. It includes pagination metadata and an array of detailed consumption records.

```json
{
  "get_consumption_detail_200_response": {
    "properties": {
      "meta": {"$ref": "#/components/schemas/PaginationWithUpdatedAt"},
      "data": {
        "items": {"$ref": "#/components/schemas/DetailedConsumption"},
        "type": "array"
      }
    },
    "type": "object"
  }
}
```

--------------------------------

### Initiate Business Registration Certificate

Source: https://developers.yousign.com/reference/post-document_analyses

Initiates the analysis of a business registration certificate. Requires the file and type, with optional workspace ID.

```APIDOC
## POST /api/documents/analyze/business_registration_certificate

### Description
Initiates the analysis of a business registration certificate.

### Method
POST

### Endpoint
/api/documents/analyze/business_registration_certificate

### Parameters
#### Request Body
- **file** (string) - Required - The file containing the data to extract. Accepted formats: PDF, PNG, JPG, JPEG. Max size: 10 MB. Max number of pages for PDF: 2.
- **type** (string) - Required - Must be "business_registration_certificate".
- **workspace_id** (string) - Optional - Scopes the Document Analysis to a specific workspace. Defaults to the default workspace if not specified.

### Request Example
{
  "file": "Binary file",
  "type": "business_registration_certificate",
  "workspace_id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c"
}

### Response
#### Success Response (200)
- **analysis_id** (string) - The ID of the initiated analysis.
- **status** (string) - The status of the analysis.
```

--------------------------------

### POST /custom_experiences

Source: https://developers.yousign.com/reference/post-custom-experience-1

Create a new custom experience configuration to define branding and UI behavior for your signature workflows.

```APIDOC
## POST /custom_experiences

### Description
Creates a new custom experience object to configure the visual identity and UI constraints for signature requests.

### Method
POST

### Endpoint
/custom_experiences

### Parameters
#### Request Body
- **name** (string) - Required - The name of the custom experience.
- **landing_page_disabled** (boolean) - Optional - Whether to disable the landing page.
- **side_panel_disabled** (boolean) - Optional - Whether to disable the side panel.
- **background_color** (string) - Optional - Hex code for background color.
- **button_color** (string) - Optional - Hex code for button color.

### Request Example
{
  "name": "My Custom Brand",
  "landing_page_disabled": false
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created custom experience.

#### Response Example
{
  "id": "89120884-d29a-4b1a-ac7b-a9e73a872795"
}
```

--------------------------------

### POST /users

Source: https://developers.yousign.com/reference/post-users-1

Create a new application user and trigger an invitation email.

```APIDOC
## POST /users

### Description
Creates a new application User and sends them an invitation email to access the Yousign platform.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **CreateUser** (object) - Required - The user creation object containing details such as email, first name, and last name.

### Request Example
{
  "email": "user@example.com",
  "firstname": "John",
  "lastname": "Doe"
}

### Response
#### Success Response (201)
- **User** (object) - The created user object.

#### Response Example
{
  "id": "user_123",
  "email": "user@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "status": "invited"
}
```

--------------------------------

### Example Rate Limit Exceeded Response Headers (cURL)

Source: https://developers.yousign.com/reference/rate-limits

This example demonstrates the HTTP response headers received when an API request exceeds the rate limit. It shows the limit for minute and hour, remaining quota, and the time until the minute quota resets.

```curl
HTTP/2 429 
< x-ratelimit-limit-hour: 1200
< x-ratelimit-limit-minute: 60
< x-ratelimit-remaining-hour: 1197
< x-ratelimit-remaining-minute: 59
< Ratelimit-Reset: 45
```

--------------------------------

### New Signer From Scratch Info Schema

Source: https://developers.yousign.com/reference/post-signature_requests-signaturerequestid-signers-1

Defines the structure for creating a new signer from scratch, including contact details and locale.

```APIDOC
## New Signer From Scratch Info Schema

### Description
This schema defines the information required to create a new signer from scratch, including their name, email, and locale.

### Object
`New_Signer_From_Scratch_info`

### Properties
- **first_name** (string) - Required - The first name of the signer. Max length: 255, Min length: 1.
- **last_name** (string) - Required - The last name of the signer. Max length: 255, Min length: 1.
- **email** (string) - Required - The email address of the signer. Max length: 100, Min length: 1.
- **phone_number** (string) - Optional - The phone number of the signer in E.164 format. Max length: 100, Min length: 1.
- **locale** (Locale) - Required - The locale for the signer.
```

--------------------------------

### POST /users

Source: https://developers.yousign.com/reference/post-users-1

Create a new user in the organization by providing the required user details.

```APIDOC
## POST /users

### Description
Creates a new user within the organization. The email address must be unique.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the new user.
- **role** (string) - Required - The role assigned to the user (admin, member).

### Request Example
{
  "email": "john.doe@example.com",
  "role": "member"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created user.

#### Response Example
{
  "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c"
}
```

--------------------------------

### GET /person/status

Source: https://developers.yousign.com/reference/signer-identification_failed

Retrieve the PEP and sanction status of a person.

```APIDOC
## GET /person/status

### Description
Retrieves the political exposure status and sanction records for a specific individual.

### Method
GET

### Endpoint
/person/status

### Parameters
#### Query Parameters
- **person_id** (string) - Required - The unique identifier for the person.

### Response
#### Success Response (200)
- **pep** (object) - Contains details about political positions.
- **sanctions** (object) - Contains active status and a list of sanction records.

#### Response Example
{
  "pep": {
    "title": "Minister of Finance",
    "active": false,
    "country_code": "FR",
    "started_on": "2020-01-01",
    "ended_on": "2021-01-01",
    "sources": [{"name": "Wikidata", "url": "https://www.opensanctions.org"}]
  },
  "sanctions": {
    "active": false,
    "records": [{
      "description": "Management ban",
      "authority": "Commercial Court of Paris",
      "country_code": "FR",
      "active": false,
      "started_on": "2020-01-01",
      "ended_on": "2021-01-01"
    }]
  }
}
```

--------------------------------

### POST /custom_experiences

Source: https://developers.yousign.com/reference/post-custom-experience-1

Create a new custom experience configuration to apply specific branding and behavioral settings to signing requests.

```APIDOC
## POST /custom_experiences

### Description
Creates a new custom experience object that defines the visual branding and functional constraints for the signing process.

### Method
POST

### Endpoint
/custom_experiences

### Parameters
#### Request Body
- **name** (string) - Required - A unique name for the custom experience (Safe String, max 255 chars).
- **background_color** (string) - Optional - Hexadecimal color value for the background.
- **button_color** (string) - Optional - Hexadecimal color value for buttons.
- **text_color** (string) - Optional - Hexadecimal color value for text.
- **download_documents_disabled** (boolean) - Optional - If true, signers cannot download documents before signing.
- **document_navigation_disabled** (boolean) - Optional - If true, signers must read each document sequentially.

### Request Example
{
  "name": "My Custom Branding",
  "background_color": "#ffffff",
  "button_color": "#000000"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created custom experience.

#### Response Example
{
  "id": "ce_123456789",
  "name": "My Custom Branding",
  "created_at": "2024-01-18T22:59:00Z"
}
```

--------------------------------

### GET /signature_requests

Source: https://developers.yousign.com/reference/get-signature_requests-1

Retrieves a paginated list of signature requests.

```APIDOC
## GET /signature_requests

### Description
Retrieve a list of signature requests with pagination support.

### Method
GET

### Endpoint
/signature_requests

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination
- **limit** (integer) - Optional - Number of items per page

### Request Example
GET /signature_requests?page=1&limit=10

### Response
#### Success Response (200)
- **meta** (object) - Pagination metadata
- **data** (array) - List of signature request objects

#### Response Example
{
  "meta": {
    "total_items": 100,
    "page": 1
  },
  "data": [
    {
      "id": "sr_123",
      "status": "initiated"
    }
  ]
}
```

--------------------------------

### POST /users

Source: https://developers.yousign.com/reference/post-users-1

Creates a new application user and triggers an invitation email, provided the organization has available licenses and the email is unique.

```APIDOC
## POST /users

### Description
Creates a new application User and sends them an invitation email. This requires an available license in the Organization and that the email address is not already in use by another User or pending Invitation.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the new user.
- **firstname** (string) - Required - The first name of the user.
- **lastname** (string) - Required - The last name of the user.

### Request Example
{
  "email": "jane.doe@example.com",
  "firstname": "Jane",
  "lastname": "Doe"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created user.
- **status** (string) - The current status of the user invitation.

#### Response Example
{
  "id": "usr_123456789",
  "status": "invited"
}
```

--------------------------------

### GET /document-analyses

Source: https://developers.yousign.com/reference/get-document_analyses

Retrieves a paginated list of document analyses.

```APIDOC
## GET /document-analyses

### Description
Retrieves a list of document analyses with pagination metadata.

### Method
GET

### Endpoint
/document-analyses

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination
- **limit** (integer) - Optional - Number of items per page

### Response
#### Success Response (200)
- **meta** (object) - Pagination information
- **data** (array) - List of DocumentAnalysisMeta objects

#### Response Example
{
  "meta": { "total_items": 10, "page": 1 },
  "data": []
}
```

--------------------------------

### POST /companies/initiate-from-json

Source: https://developers.yousign.com/reference/post-verifications-companies

Initiates a company verification process using the company registration number and country code.

```APIDOC
## POST /companies/initiate-from-json

### Description
Initiates a company verification process by providing the exact company number and the country of registration.

### Method
POST

### Endpoint
/companies/initiate-from-json

### Parameters
#### Request Body
- **company_number** (string) - Required - The exact company registration number.
- **country_code** (string) - Required - The country where the company is registered (FR, GB, BE, CH, NL, ES, DE).
- **workspace_id** (string) - Optional - UUID of the workspace.
- **company_name** (string) - Optional - Required for German (DE) companies.

### Request Example
{
  "company_number": "794513986",
  "country_code": "FR"
}
```

--------------------------------

### GET /contacts

Source: https://developers.yousign.com/reference/get-contacts-1

Retrieves a list of contacts, with support for pagination.

```APIDOC
## GET /contacts

### Description
Retrieves a list of contacts. Supports pagination via the `meta` object in the response.

### Method
GET

### Endpoint
/contacts

### Parameters

#### Query Parameters
(No specific query parameters are detailed in the provided schema for this endpoint, but standard pagination parameters might be expected.)

### Request Example
(No request body is expected for a GET request)

### Response
#### Success Response (200)
- **meta** (object) - Pagination information.
- **data** (array) - An array of Contact objects.
  - **items** (object) - Represents a single Contact object (details not provided in schema).

#### Response Example
```json
{
  "meta": {
    "pagination_details": "..."
  },
  "data": [
    {
      "contact_details": "..."
    },
    {
      "contact_details": "..."
    }
  ]
}
```
```

--------------------------------

### GET /insurance-extraction

Source: https://developers.yousign.com/reference/signer-link_opened

Retrieves the structured data extracted from an insurance document.

```APIDOC
## GET /insurance-extraction

### Description
Retrieves the extracted fields from an insurance document, including policy holder information, contract details, and historical data like drivers and incidents.

### Method
GET

### Endpoint
/insurance-extraction

### Parameters
#### Query Parameters
- **document_id** (string) - Required - The unique identifier of the document to process.

### Response
#### Success Response (200)
- **policy_holder_address** (string) - Address of the policy holder.
- **policy_holder_birth_date** (string) - Birth date of the policy holder.
- **insurance_score** (string) - Bonus/malus coefficient.
- **issuance_date** (string) - Date of document issuance.
- **effective_start_date** (string) - Start date of the contract.
- **active_contract** (boolean) - Status of the contract.
- **contract_cancellation_date** (string) - Date of cancellation if applicable.
- **vehicle_model** (string) - Insured vehicle model.
- **vehicle_license_plate** (string) - Vehicle license plate.
- **drivers_information** (array) - List of covered drivers.
- **incidents_information** (array) - List of insurance claims.

#### Response Example
{
  "policy_holder_address": "123 Main St, Paris",
  "active_contract": true,
  "vehicle_model": "Renault Clio",
  "drivers_information": [
    {
      "driver_full_name": "John Doe",
      "driver_birth_date": "1990-01-01",
      "coverage_start_date": "2023-01-01",
      "driver_license_number": "ABC12345",
      "driver_license_category": "B",
      "driver_license_issuance_date": "2010-05-15"
    }
  ]
}
```

--------------------------------

### Initiate Bank Account Connection Verification (OpenAPI)

Source: https://developers.yousign.com/reference/post-verifications-bank_account_connections

This snippet defines the OpenAPI specification for initiating a Bank Account Connection Verification. It outlines the request body schema, expected responses (including a pending state example), and potential error responses.

```json
{
  "openapi": "3.0.0",
  "info": {
    "contact": {
      "email": "contact@yousign.com",
      "name": "Support",
      "url": "https://yousign.com/contact"
    },
    "description": "Build the best experience of digital signature through your own platform. Increase your conversion rates, leverage your data and reduce your costs with Yousign API.",
    "license": {
      "name": "proprietary",
      "url": "https://yousign.com/terms"
    },
    "title": "Public Api v3",
    "version": "3.0"
  },
  "servers": [
    {
      "description": "Sandbox URL",
      "url": "https://api-sandbox.yousign.app/v3"
    },
    {
      "description": "Production URL",
      "url": "https://api.yousign.app/v3"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "description": "KYC Process of verifying the ownership of a bank account.",
      "name": "Bank Account Connection Verification"
    }
  ],
  "paths": {
    "/verifications/bank_account_connections": {
      "post": {
        "description": "Initiate a new Bank Account Connection Verification flow and returns a URL to redirect the user to complete the connection process.",
        "operationId": "post-verifications-bank_account_connections",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateBankAccountConnection"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "examples": {
                  "pending": {
                    "summary": "Pending - Verification Is In Progress: On Creation The Status Is Always Pending",
                    "value": {
                      "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
                      "workspace_id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
                      "workflow_session_id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
                      "previous_attempt_id": "9412b83b-b4b9-4a94-97b5-2b43dfa4cde4",
                      "created_at": "2025-07-23T18:22:00+00:00",
                      "updated_at": "2025-07-23T18:22:00+00:00",
                      "status": "pending",
                      "status_codes": [],
                      "data_anonymized": false,
                      "data": {
                        "account_type": null,
                        "account_identifiers": {
                          "iban": null,
                          "bic": null
                        },
                        "bank_name": null,
                        "parties": [],
                        "checks": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BankAccountConnectionFull"
                }
              }
            },
            "description": "Created",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/rateLimit-limit"
              },
              "X-RateLimit-Limit-Hour": {
                "$ref": "#/components/headers/rateLimit-limit-hour"
              },
              "X-RateLimit-Limit-Minute": {
                "$ref": "#/components/headers/rateLimit-limit-minute"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/rateLimit-remaining"
              },
              "X-RateLimit-Remaining-Hour": {
                "$ref": "#/components/headers/rateLimit-remaining-hour"
              },
              "X-RateLimit-Remaining-Minute": {
                "$ref": "#/components/headers/rateLimit-remaining-minute"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/rateLimit-reset"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestResponse"
                }
              }
            },
            "description": "Bad request",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/rateLimit-limit"
              },
              "X-RateLimit-Limit-Hour": {
                "$ref": "#/components/headers/rateLimit-limit-hour"
              },
              "X-RateLimit-Limit-Minute": {
                "$ref": "#/components/headers/rateLimit-limit-minute"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/rateLimit-remaining"
              },
              "X-RateLimit-Remaining-Hour": {
                "$ref": "#/components/headers/rateLimit-remaining-hour"
              },
              "X-RateLimit-Remaining-Minute": {
                "$ref": "#/components/headers/rateLimit-remaining-minute"
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### New Signer From Scratch API

Source: https://developers.yousign.com/reference/post-signature_requests-signaturerequestid-signers-1

This API allows you to create a new signer from scratch, specifying their details, fields, and signature preferences.

```APIDOC
## POST /api/signers

### Description
Create a new signer from scratch. This endpoint allows for detailed configuration of the signer, including their information, assigned fields, signature level, and authentication methods.

### Method
POST

### Endpoint
/api/signers

### Parameters
#### Request Body
- **info** (object) - Required - Information about the signer.
- **fields** (array) - Optional - Fields to assign to the Signer. Multiple Fields can be added simultaneously.
- **insert_after_id** (string) - Optional - ID of the recipient this one must follow in an ordered flow. Requires `custom_recipient_order` to be enabled.
- **group_with_id** (string) - Optional - ID of another recipient; both will act in parallel. Only available when `custom_recipient_order` is enabled.
- **signature_level** (string) - Required - The level of signature required (e.g., `electronic_signature`, `advanced_electronic_signature`, `qualified_electronic_signature`).
- **signature_authentication_mode** (string) - Optional - Method to authenticate the Signers (e.g., `otp_email`, `otp_sms`, `no_otp`).
- **redirect_urls** (object) - Optional - URLs for redirection after signer actions.
- **custom_text** (object) - Optional - Custom text elements for the signer's experience.
- **delivery_mode** (object) - Optional - Specifies how the signer will receive documents.
- **identification_attestation_id** (string) - Optional - An identifier for identity attestation.
- **sms_notification** (object) - Optional - Configuration for SMS notifications.
- **email_notification** (object) - Optional - Configuration for email notifications.
- **pre_identity_verification_required** (boolean) - Optional - Defines if identity document upload is required before signing.

### Request Example
```json
{
  "info": {
    "email": "signer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+1234567890"
  },
  "fields": [
    {
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 100
    }
  ],
  "signature_level": "advanced_electronic_signature",
  "signature_authentication_mode": "otp_sms",
  "delivery_mode": {
    "mode": "email"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created signer.
- **status** (string) - The current status of the signer.

#### Response Example
```json
{
  "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
  "status": "pending"
}
```
```

--------------------------------

### GET /insurance-document-extraction

Source: https://developers.yousign.com/reference/signer-identification_blocked

Retrieves the structured data extracted from an insurance document.

```APIDOC
## GET /insurance-document-extraction

### Description
Retrieves the extracted fields from an insurance document, including policy holder information, vehicle details, and historical incident data.

### Method
GET

### Endpoint
/insurance-document-extraction

### Parameters
#### Query Parameters
- **document_id** (string) - Required - The ID of the document to extract data from.

### Response
#### Success Response (200)
- **policy_holder_address** (string) - Address of the policy holder.
- **policy_holder_birth_date** (string) - Birth date of the policy holder.
- **insurance_score** (string) - Bonus/malus coefficient.
- **issuance_date** (string) - Date the document was issued.
- **effective_start_date** (string) - Start date of the contract.
- **active_contract** (boolean) - Status of the contract.
- **vehicle_model** (string) - Model of the vehicle.
- **vehicle_license_plate** (string) - License plate of the vehicle.
- **drivers_information** (array) - List of covered drivers.
- **incidents_information** (array) - List of recorded claims.

#### Response Example
{
  "policy_holder_address": "123 Main St, Paris",
  "active_contract": true,
  "vehicle_model": "Renault Clio",
  "drivers_information": [
    {
      "driver_full_name": "John Doe",
      "driver_license_number": "ABC12345"
    }
  ]
}
```

--------------------------------

### GET /insurance-extraction

Source: https://developers.yousign.com/reference/signer-identification_failed

Retrieves extracted insurance data from a processed document.

```APIDOC
## GET /insurance-extraction

### Description
Retrieves the structured insurance information extracted from a document, including policy details and driver history.

### Method
GET

### Endpoint
/insurance-extraction

### Parameters
#### Query Parameters
- **document_id** (string) - Required - The unique identifier of the processed document.

### Response
#### Success Response (200)
- **policy_holder_address** (string) - Address of the policy holder.
- **policy_holder_birth_date** (string) - Birth date of the policy holder.
- **insurance_score** (string) - Bonus/malus coefficient.
- **issuance_date** (string) - Date of document issuance.
- **effective_start_date** (string) - Start date of the contract.
- **active_contract** (boolean) - Contract status.
- **vehicle_model** (string) - Model of the vehicle.
- **vehicle_license_plate** (string) - License plate number.
- **drivers_information** (array) - List of covered drivers.
- **incidents_information** (array) - List of recorded claims.

#### Response Example
{
  "policy_holder_address": "123 Main St, Paris",
  "active_contract": true,
  "vehicle_model": "Renault Clio",
  "drivers_information": [
    {
      "driver_full_name": "John Doe",
      "driver_license_number": "ABC12345"
    }
  ]
}
```

--------------------------------

### POST /workspaces

Source: https://developers.yousign.com/reference/post-workspace-1

Create a new workspace by providing a name and an optional external name.

```APIDOC
## POST /workspaces

### Description
Creates a new workspace in the system. The name is required and must adhere to safe string formatting.

### Method
POST

### Endpoint
/workspaces

### Parameters
#### Request Body
- **name** (string) - Required - The name of the workspace. Max length 200.
- **external_name** (string) - Optional - An external identifier for the workspace. Max length 200.

### Request Example
{
  "name": "Sales",
  "external_name": "UK Sales"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created workspace.

#### Response Example
{
  "id": "89120884-d29a-4b1a-ac7b-a9e73a872795"
}
```

--------------------------------

### GET /document-analysis/tax-notice

Source: https://developers.yousign.com/reference/signature_request-permanently_deleted

Retrieves the extracted data from a tax notice document.

```APIDOC
## GET /document-analysis/tax-notice

### Description
Retrieves the extracted data from a tax notice document, including fiscal numbers, reference income, and issuance dates.

### Method
GET

### Endpoint
/document-analysis/tax-notice

### Response
#### Success Response (200)
- **full_name** (string) - The holder full name
- **fiscal_number_1** (string) - Fiscal number of the first declarant
- **tax_notice_reference** (string) - Tax notice reference number
- **reference_income** (number) - Fiscal reference income

#### Response Example
{
  "full_name": "Doe John",
  "fiscal_number_1": "0312345678901",
  "tax_notice_reference": "2412B01234567",
  "reference_income": 30000
}
```