### Receiving Webhook Payload Example

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Illustrates an example of a webhook payload received by the configured endpoint when an inquiry status changes. This shows the structure of the event data, including status and decision.

```json
POST https://your-app.com/webhooks/persona
{
  "data": {
    "type": "event",
    "id": "evt_123",
    "attributes": {
      "name": "inquiry.completed",
      "payload": {
        "data": {
          "type": "inquiry",
          "id": "inq_XYZ789",
          "attributes": {
            "status": "completed",
            "decision": "approved"
          }
        }
      }
    }
  }
}
```

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

### GET /api/v1/inquiries/{id}

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Poll the API to check verification status and retrieve results.

```APIDOC
## GET /api/v1/inquiries/{id}

### Description
Poll the API to check verification status and retrieve results.

### Method
GET

### Endpoint
/api/v1/inquiries/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the inquiry to retrieve.

### Response
#### Success Response (200)
- **data** (object) - The inquiry object.
  - **type** (string) - The type of the object, "inquiry".
  - **id** (string) - The unique ID of the inquiry.
  - **attributes** (object) - The inquiry attributes.
    - **status** (string) - The current status of the inquiry (e.g., "completed").
    - **decision** (string) - The verification decision (e.g., "approved").
    - **created-at** (string) - The timestamp when the inquiry was created.
    - **completed-at** (string) - The timestamp when the inquiry was completed.
  - **relationships** (object) - Relationships to other resources.
    - **verifications** (object) - Information about associated verifications.
      - **data** (array) - An array of verification objects.
        - **type** (string) - The type of verification (e.g., "verification/government-id").
        - **id** (string) - The ID of the verification.

#### Response Example
```json
{
  "data": {
    "type": "inquiry",
    "id": "inq_XYZ789",
    "attributes": {
      "status": "completed",
      "decision": "approved",
      "created-at": "2025-01-15T10:30:00Z",
      "completed-at": "2025-01-15T10:35:00Z"
    },
    "relationships": {
      "verifications": {
        "data": [
          {"type": "verification/government-id", "id": "ver_ABC123"}
        ]
      }
    }
  }
}
```
```

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

### GET /api/v1/reports/{reportId}

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Retrieves detailed verification reports, including extracted data and decision factors.

```APIDOC
## GET /api/v1/reports/{reportId}

### Description
Retrieves detailed verification reports, including extracted data and decision factors. This endpoint allows access to the results of verification processes.

### Method
GET

### Endpoint
/api/v1/reports/{reportId}

### Parameters
#### Path Parameters
- **reportId** (string) - Required - The unique identifier of the report to retrieve.

### Response
#### Success Response (200)
- **data** (object) - The report data.
  - **type** (string) - The type of report (e.g., 'report/government-id').
  - **id** (string) - The unique ID of the report.
  - **attributes** (object) - Report attributes.
    - **status** (string) - The status of the report (e.g., 'ready').
    - **extracted-data** (object) - A key-value map of data extracted during verification.
      - **name-first** (string) - First name.
      - **name-last** (string) - Last name.
      - **birthdate** (string) - Birthdate in YYYY-MM-DD format.
      - **document-number** (string) - The document number.
      - **expiration-date** (string) - The expiration date of the document.
      - **issuing-country** (string) - The country that issued the document.
    - **checks** (object) - Results of various verification checks.
      - **document-validity** (string) - Validity check result (e.g., 'passed').
      - **document-expired** (string) - Expiration check result (e.g., 'passed').
      - **document-tampering** (string) - Tampering check result (e.g., 'passed').

#### Response Example
```json
{
  "data": {
    "type": "report/government-id",
    "id": "rep_ABC123",
    "attributes": {
      "status": "ready",
      "extracted-data": {
        "name-first": "John",
        "name-last": "Doe",
        "birthdate": "1990-01-15",
        "document-number": "D1234567",
        "expiration-date": "2030-01-15",
        "issuing-country": "US"
      },
      "checks": {
        "document-validity": "passed",
        "document-expired": "passed",
        "document-tampering": "passed"
      }
    }
  }
}
```
```

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

### Retrieving Inquiry Status using cURL

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Explains how to retrieve the status and results of an inquiry by making a GET request to the /inquiries/{inquiry_id} endpoint. This is used for polling the verification status.

```bash
curl https://withpersona.com/api/v1/inquiries/inq_XYZ789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

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

### POST /api/v1/inquiries

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Create an inquiry before directing users through the verification flow.

```APIDOC
## POST /api/v1/inquiries

### Description
Create an inquiry before directing users through the verification flow.

### Method
POST

### Endpoint
/api/v1/inquiries

### Parameters
#### Request Body
- **data** (object) - Required - Contains the inquiry details.
  - **type** (string) - Required - Must be "inquiry".
  - **attributes** (object) - Required - The inquiry attributes.
    - **inquiry-template-id** (string) - Required - The ID of the inquiry template.
    - **reference-id** (string) - Optional - A unique identifier for the inquiry.
    - **note** (string) - Optional - A note for the inquiry.

### Request Example
```json
{
  "data": {
    "type": "inquiry",
    "attributes": {
      "inquiry-template-id": "itmpl_ABC123",
      "reference-id": "user_12345",
      "note": "New customer onboarding"
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created inquiry object.
  - **type** (string) - The type of the object, "inquiry".
  - **id** (string) - The unique ID of the inquiry.
  - **attributes** (object) - The inquiry attributes.
    - **status** (string) - The current status of the inquiry (e.g., "created").
    - **reference-id** (string) - The reference ID provided.

#### Response Example
```json
{
  "data": {
    "type": "inquiry",
    "id": "inq_XYZ789",
    "attributes": {
      "status": "created",
      "reference-id": "user_12345"
    }
  }
}
```
```

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

### API Authentication using cURL

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Demonstrates how to authenticate API requests using an API key via the Authorization header in cURL. This is a foundational step for all subsequent API interactions.

```bash
curl https://withpersona.com/api/v1/inquiries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

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

### Create Transaction with Workflow (Bash)

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Initiates a transaction and triggers an automated verification workflow. Requires an API key and specifies transaction details and the workflow to be used. The response includes the transaction status and associated verifications.

```bash
curl -X POST https://withpersona.com/api/v1/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "transaction",
      "attributes": {
        "transaction-type": "account_opening",
        "reference-id": "txn_user_12345",
        "fields": {
          "name-first": "John",
          "name-last": "Doe",
          "email-address": "john.doe@example.com",
          "phone-number": "+1-555-0123"
        }
      },
      "relationships": {
        "workflow": {
          "data": {
            "type": "workflow",
            "id": "wf_KYC_FLOW_001"
          }
        }
      }
    }
  }'
```

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

### Pre-creating Inquiries using cURL

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Shows how to create a new inquiry before initiating the verification flow. This involves a POST request to the /inquiries endpoint with necessary attributes like inquiry-template-id and reference-id.

```bash
curl -X POST https://withpersona.com/api/v1/inquiries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "inquiry",
      "attributes": {
        "inquiry-template-id": "itmpl_ABC123",
        "reference-id": "user_12345",
        "note": "New customer onboarding"
      }
    }
  }'
```

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

### POST /api/v1/inquiries

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Handles idempotent requests for creating inquiries, ensuring safe retries.

```APIDOC
## POST /api/v1/inquiries (Idempotency)

### Description
Ensures request deduplication for safe retries using idempotency keys. Subsequent requests with the same key will return the original response, preventing duplicate actions.

### Method
POST

### Endpoint
/api/v1/inquiries

### Parameters
#### Request Body
- **data** (object) - Required - The main payload for the inquiry.
  - **type** (string) - Required - Must be 'inquiry'.
  - **attributes** (object) - Required - Contains inquiry-specific details.
    - **inquiry-template-id** (string) - Required - The ID of the inquiry template to use.
    - **reference-id** (string) - Required - A unique identifier for the inquiry.

#### Headers
- **Idempotency-Key** (string) - Required - A unique key for the request to ensure idempotency. Keys expire after 24 hours.

### Request Example
```json
{
  "data": {
    "type": "inquiry",
    "attributes": {
      "inquiry-template-id": "itmpl_ABC123",
      "reference-id": "user_12345"
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created inquiry object.
  - **type** (string) - The type of the object, 'inquiry'.
  - **id** (string) - The unique ID of the inquiry.
  - **attributes** (object) - Inquiry attributes.
    - **inquiry-template-id** (string) - The ID of the inquiry template.
    - **reference-id** (string) - The reference ID for the inquiry.

#### Response Example
```json
{
  "data": {
    "type": "inquiry",
    "id": "inq_XYZ789",
    "attributes": {
      "inquiry-template-id": "itmpl_ABC123",
      "reference-id": "user_12345"
    }
  }
}
```
```

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

### Retrieve Verification Report (Bash)

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Fetches a detailed verification report using a report ID. This allows access to extracted data, check results, and decision factors. Requires an API key for authentication.

```bash
curl https://withpersona.com/api/v1/reports/rep_ABC123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

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

### API Authentication

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Authenticate all API requests using API keys in the Authorization header.

```APIDOC
## API Authentication

Authenticate all API requests using API keys in the Authorization header.

```bash
curl https://withpersona.com/api/v1/inquiries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```
```

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

### POST /api/v1/webhooks

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Configure webhook endpoints to receive real-time updates on verification status changes.

```APIDOC
## POST /api/v1/webhooks

### Description
Configure webhook endpoints to receive real-time updates on verification status changes.

### Method
POST

### Endpoint
/api/v1/webhooks

### Parameters
#### Request Body
- **data** (object) - Required - Contains the webhook details.
  - **type** (string) - Required - Must be "webhook".
  - **attributes** (object) - Required - The webhook attributes.
    - **url** (string) - Required - The URL to receive webhook events.
    - **enabled** (boolean) - Required - Whether the webhook is enabled.
    - **events** (array) - Required - A list of events to subscribe to.
      - (string) - The name of an event (e.g., "inquiry.completed").

### Request Example
```json
{
  "data": {
    "type": "webhook",
    "attributes": {
      "url": "https://your-app.com/webhooks/persona",
      "enabled": true,
      "events": [
        "inquiry.completed",
        "inquiry.approved",
        "inquiry.declined"
      ]
    }
  }
}
```

### Webhook Payload Example
```json
{
  "data": {
    "type": "event",
    "id": "evt_123",
    "attributes": {
      "name": "inquiry.completed",
      "payload": {
        "data": {
          "type": "inquiry",
          "id": "inq_XYZ789",
          "attributes": {
            "status": "completed",
            "decision": "approved"
          }
        }
      }
    }
  }
}
```
```

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

### Creating Direct Government ID Verification using cURL

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Shows how to perform a direct government ID verification without using the inquiry flow, intended for enterprise customers. This requires a POST request to /verifications/government-id with front and back photos, name, and birthdate.

```bash
curl -X POST https://withpersona.com/api/v1/verifications/government-id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "verification/government-id",
      "attributes": {
        "front-photo": "data:image/jpeg;base64,/9j/4AAQ...",
        "back-photo": "data:image/jpeg;base64,/9j/4AAQ...",
        "name-first": "John",
        "name-last": "Doe",
        "birthdate": "1990-01-15"
      }
    }
  }'
```

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

### Handle Idempotent Requests (Bash)

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Demonstrates how to make idempotent requests to the Persona API by including an 'Idempotency-Key' header. This ensures that duplicate requests are handled safely by returning the original response. Idempotency keys expire after 24 hours.

```bash
curl -X POST https://withpersona.com/api/v1/inquiries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique_request_12345" \
  -d '{
    "data": {
      "type": "inquiry",
      "attributes": {
        "inquiry-template-id": "itmpl_ABC123",
        "reference-id": "user_12345"
      }
    }
  }'
```

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

### POST /api/v1/transactions

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Creates a new transaction and triggers automated verification workflows.

```APIDOC
## POST /api/v1/transactions

### Description
Creates a new transaction and triggers automated verification workflows. This endpoint allows you to initiate a process that can include account opening and subsequent verification steps.

### Method
POST

### Endpoint
/api/v1/transactions

### Parameters
#### Request Body
- **data** (object) - Required - The main payload for the transaction.
  - **type** (string) - Required - Must be 'transaction'.
  - **attributes** (object) - Required - Contains transaction-specific details.
    - **transaction-type** (string) - Required - The type of transaction (e.g., 'account_opening').
    - **reference-id** (string) - Required - A unique identifier for the transaction.
    - **fields** (object) - Optional - A key-value map of fields to be included in the transaction.
      - **name-first** (string) - Optional - The first name.
      - **name-last** (string) - Optional - The last name.
      - **email-address** (string) - Optional - The email address.
      - **phone-number** (string) - Optional - The phone number.
  - **relationships** (object) - Optional - Defines relationships to other entities.
    - **workflow** (object) - Required if a workflow should be associated.
      - **data** (object) - Required.
        - **type** (string) - Must be 'workflow'.
        - **id** (string) - Required - The ID of the workflow to associate with the transaction.

### Request Example
```json
{
  "data": {
    "type": "transaction",
    "attributes": {
      "transaction-type": "account_opening",
      "reference-id": "txn_user_12345",
      "fields": {
        "name-first": "John",
        "name-last": "Doe",
        "email-address": "john.doe@example.com",
        "phone-number": "+1-555-0123"
      }
    },
    "relationships": {
      "workflow": {
        "data": {
          "type": "workflow",
          "id": "wf_KYC_FLOW_001"
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created transaction object.
  - **type** (string) - The type of the object, 'transaction'.
  - **id** (string) - The unique ID of the transaction.
  - **attributes** (object) - Transaction attributes.
    - **status** (string) - The current status of the transaction (e.g., 'processing').
    - **transaction-type** (string) - The type of transaction.
  - **relationships** (object) - Relationships associated with the transaction.
    - **verifications** (object) - An array of associated verification objects.
      - **data** (array) - List of verification objects.
        - **type** (string) - The type of verification.
        - **id** (string) - The ID of the verification.

#### Response Example
```json
{
  "data": {
    "type": "transaction",
    "id": "txn_789",
    "attributes": {
      "status": "processing",
      "transaction-type": "account_opening"
    },
    "relationships": {
      "verifications": {
        "data": [
          {"type": "verification/database", "id": "ver_DB_001"}
        ]
      }
    }
  }
}
```
```

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

### Configuring Webhook Endpoint using cURL

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Demonstrates how to configure a webhook endpoint to receive real-time updates on verification status changes. This involves a POST request to the /webhooks endpoint with the desired URL and event subscriptions.

```bash
# Configure webhook endpoint
curl -X POST https://withpersona.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "webhook",
      "attributes": {
        "url": "https://your-app.com/webhooks/persona",
        "enabled": true,
        "events": [
          "inquiry.completed",
          "inquiry.approved",
          "inquiry.declined"
        ]
      }
    }
  }'
```

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

### Error Handling

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Provides guidance on handling API errors with structured responses and implementing retry logic.

```APIDOC
## Error Handling

### Description
Handle API errors with structured error responses and implement retry logic for transient issues like rate limiting or server errors.

### Error Response Structure
When an error occurs, the API typically returns a JSON object with an `errors` array. Each object in the array contains details about the error.

```json
{
  "errors": [
    {
      "code": "string", // An error code
      "detail": "string", // A human-readable description of the error
      "id": "string", // An error identifier
      "status": "string" // The HTTP status code
    }
  ]
}
```

### Common Error Codes and Handling
- **400 Bad Request / 422 Unprocessable Entity**: Indicates validation errors in the request. These errors are typically not retryable.
- **429 Too Many Requests**: Indicates rate limiting. Implement exponential backoff with a `Retry-After` header if provided.
- **5xx Server Error**: Indicates a server-side issue. These errors are transient and should be retried with an appropriate delay.

### Example: Retrying API Calls (JavaScript)
```javascript
async function createInquiryWithRetry(apiKey, templateId, referenceId) {
  const maxRetries = 3;
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await fetch('https://withpersona.com/api/v1/inquiries', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': `inquiry_${referenceId}_${Date.now()}`
        },
        body: JSON.stringify({
          data: {
            type: 'inquiry',
            attributes: {
              'inquiry-template-id': templateId,
              'reference-id': referenceId
            }
          }
        })
      });

      if (response.ok) {
        return await response.json();
      }

      const error = await response.json();

      // Handle rate limiting
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        attempt++;
        continue;
      }

      // Handle validation errors (don't retry)
      if (response.status === 400 || response.status === 422) {
        throw new Error(`Validation error: ${error.errors[0].detail}`);
      }

      // Handle server errors (retry)
      if (response.status >= 500) {
        attempt++;
        await new Promise(resolve => setTimeout(resolve, 2000 * attempt)); // Exponential backoff
        continue;
      }

      throw new Error(`API error: ${error.errors[0].detail}`);
    } catch (err) {
      if (attempt === maxRetries - 1) throw err; // Last attempt failed
      attempt++;
    }
  }
}

// Usage:
// const inquiry = await createInquiryWithRetry(
//   'api_live_ABC123',
//   'itmpl_XYZ789',
//   'user_12345'
// );
```
```

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

### POST /api/v1/verifications/government-id

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

Perform identity verification using government-issued IDs (Enterprise only).

```APIDOC
## POST /api/v1/verifications/government-id

### Description
Perform identity verification using government-issued IDs (Enterprise only).

### Method
POST

### Endpoint
/api/v1/verifications/government-id

### Parameters
#### Request Body
- **data** (object) - Required - Contains the verification details.
  - **type** (string) - Required - Must be "verification/government-id".
  - **attributes** (object) - Required - The verification attributes.
    - **front-photo** (string) - Required - Base64 encoded image of the front of the ID.
    - **back-photo** (string) - Optional - Base64 encoded image of the back of the ID.
    - **name-first** (string) - Required - The first name of the individual.
    - **name-last** (string) - Required - The last name of the individual.
    - **birthdate** (string) - Required - The birthdate of the individual (YYYY-MM-DD).

### Request Example
```json
{
  "data": {
    "type": "verification/government-id",
    "attributes": {
      "front-photo": "data:image/jpeg;base64,/9j/4AAQ...",
      "back-photo": "data:image/jpeg;base64,/9j/4AAQ...",
      "name-first": "John",
      "name-last": "Doe",
      "birthdate": "1990-01-15"
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The verification object.
  - **type** (string) - The type of the object, "verification/government-id".
  - **id** (string) - The unique ID of the verification.
  - **attributes** (object) - The verification attributes.
    - **status** (string) - The status of the verification (e.g., "passed").
    - **checks** (object) - Results of various verification checks.
      - **document-authenticity** (string) - Result of document authenticity check.
      - **name-match** (string) - Result of name match check.
      - **birthdate-match** (string) - Result of birthdate match check.

#### Response Example
```json
{
  "data": {
    "type": "verification/government-id",
    "id": "ver_ABC123",
    "attributes": {
      "status": "passed",
      "checks": {
        "document-authenticity": "passed",
        "name-match": "passed",
        "birthdate-match": "passed"
      }
    }
  }
}
```
```

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

### Implement Robust Error Handling with Retries (JavaScript)

Source: https://context7.com/context7/docs_withpersona_com-reference-introduction/llms.txt

A JavaScript function to create inquiries with built-in retry logic for handling API errors, including rate limiting and server errors. It implements a maximum number of retries and exponential backoff for failed requests, while non-retryable errors like validation failures are thrown immediately.

```javascript
async function createInquiryWithRetry(apiKey, templateId, referenceId) {
  const maxRetries = 3;
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await fetch('https://withpersona.com/api/v1/inquiries', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': `inquiry_${referenceId}_${Date.now()}`
        },
        body: JSON.stringify({
          data: {
            type: 'inquiry',
            attributes: {
              'inquiry-template-id': templateId,
              'reference-id': referenceId
            }
          }
        })
      });

      if (response.ok) {
        return await response.json();
      }

      const error = await response.json();

      // Handle rate limiting
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        attempt++;
        continue;
      }

      // Handle validation errors (don't retry)
      if (response.status === 400 || response.status === 422) {
        throw new Error(`Validation error: ${error.errors[0].detail}`);
      }

      // Handle server errors (retry)
      if (response.status >= 500) {
        attempt++;
        await new Promise(resolve => setTimeout(resolve, 2000 * attempt));
        continue;
      }

      throw new Error(`API error: ${error.errors[0].detail}`);
    } catch (err) {
      if (attempt === maxRetries - 1) throw err;
      attempt++;
    }
  }
}

// Usage:
// const inquiry = await createInquiryWithRetry(
//   'api_live_ABC123',
//   'itmpl_XYZ789',
//   'user_12345'
// );
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.