> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Form Response

> Retrieve complete response data including form answers and attachments.

Retrieve complete form response data including answers and attachments.

<Note>
  Form responses are called **responses** in the API. Each form (request) can have one or more responses as contacts fill them out.
</Note>

## Response Formats

The endpoint supports two response formats controlled by the `Accept` header:

| Format   | Accept Header      | Description                                                   |
| -------- | ------------------ | ------------------------------------------------------------- |
| **JSON** | `application/json` | Structured data including all form fields and file references |
| **PDF**  | `application/pdf`  | Generated PDF of the complete form response                   |

## Response Fields

### Response Attributes

| Field          | Type        | Description                                             |
| -------------- | ----------- | ------------------------------------------------------- |
| `$created_at`  | string      | ISO 8601 timestamp when response was created            |
| `$updated_at`  | string      | ISO 8601 timestamp of last update                       |
| `completed_at` | string/null | ISO 8601 timestamp when completed (null if pending)     |
| `declined_at`  | string/null | ISO 8601 timestamp when declined (null if not declined) |
| `user`         | object      | Contact information who filled the form                 |
| `data`         | object      | Form field values keyed by field name                   |
| `rating`       | string      | Optional rating provided by the contact                 |

### User Object

| Field         | Type   | Description                                       |
| ------------- | ------ | ------------------------------------------------- |
| `email`       | string | Contact email address                             |
| `given_name`  | string | Contact first name                                |
| `family_name` | string | Contact last name                                 |
| `phone`       | string | Contact phone number                              |
| `locale`      | string | Language used to fill the form (e.g., `en`, `fr`) |

## Completion Status

| Status        | Description                       | Indicators                                            |
| ------------- | --------------------------------- | ----------------------------------------------------- |
| **Pending**   | Form started but not submitted    | `completed_at: null`, `declined_at: null`             |
| **Completed** | Form successfully submitted       | `completed_at` timestamp present, `declined_at: null` |
| **Declined**  | Contact declined to fill the form | `completed_at: null`, `declined_at` timestamp present |

## Finding Response IDs

Response IDs are included when you retrieve a form. Use the relationships to find responses:

```javascript theme={null}
// Get a form with its responses
const requestResponse = await fetch(
  `https://connect.penbox.io/v1/requests/${requestId}`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data, included } = await requestResponse.json();

// Extract response IDs from relationships
const responseIds = data.relationships.responses.data.map(r => r.id);

// Fetch each response
for (const responseId of responseIds) {
  const res = await fetch(
    `https://connect.penbox.io/v1/responses/${responseId}`,
    {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    }
  );
  const responseData = await res.json();
  console.log('Response data:', responseData.data.attributes.data);
}
```

## Accessing Form Data

The `data` attribute contains all form field values:

```javascript theme={null}
const { data } = await fetch(
  `https://connect.penbox.io/v1/responses/${responseId}`,
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
).then(r => r.json());

const formData = data.attributes.data;

// Access specific fields
console.log('Company name:', formData.company_name);
console.log('Registration number:', formData.registration_number);

// Check completion status
const isCompleted = data.attributes.completed_at !== null;
const isDeclined = data.attributes.declined_at !== null;
```

## Working with Uploaded Files

Responses include references to uploaded files in the `included` array:

```javascript theme={null}
const { data, included } = await fetch(
  `https://connect.penbox.io/v1/responses/${responseId}`,
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
).then(r => r.json());

// Find files in the included array
const files = included.filter(item => item.type === 'attachments');

for (const file of files) {
  console.log('File:', file.attributes.name);
  console.log('Type:', file.attributes.type);
  console.log('Size:', file.attributes.metadata.size);

  // Download the file using the Files endpoint
  const fileUrl = `https://connect.penbox.io/v1/attachments/${file.id}`;
}
```

See [Get File](/api-reference/attachments/get-attachment) for download details.

## Response Codes

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Success - Response data retrieved       |
| `401` | Unauthorized - Invalid access token     |
| `403` | Forbidden - No access to this response  |
| `404` | Not Found - Response doesn't exist      |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error           |

<Note>
  Responses are automatically created when a contact starts filling out a form. Initially, they contain partial data and no completion timestamp.
</Note>

<Warning>
  Once a response is completed (`completed_at` is set), it becomes immutable. You cannot modify the data or user information.
</Warning>


## OpenAPI

````yaml GET /responses/{id}
openapi: 3.0.0
info:
  title: Penbox API
  version: '1.0'
  description: >-
    The Penbox API provides programmatic access to Penbox's form management,
    case management, and document processing capabilities. Authenticate using
    Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
  - url: https://connect.penbox.io/v1
    description: Production
  - url: https://connect.aiboov.com/v1
    description: Staging
security:
  - BearerAuth: []
paths:
  /responses/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Response UUID
        schema:
          type: string
          format: uuid
    get:
      summary: Get Response
      description: Retrieve complete response data including form answers and attachments.
      operationId: get-response
      parameters:
        - name: Accept
          in: header
          description: 'Response format: application/json or application/pdf'
          schema:
            type: string
            enum:
              - application/json
              - application/pdf
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDetailed'
            application/pdf:
              schema:
                type: string
                format: binary
                description: PDF rendering of the response
components:
  schemas:
    ResponseDetailed:
      allOf:
        - $ref: '#/components/schemas/ResponseFlat'
      description: Detailed response with all nested data
    ResponseFlat:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Response UUID
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the response was completed
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        data:
          type: object
          description: Form field values
        user:
          type: object
          properties:
            anonymous:
              type: boolean
            ip:
              type: string
            email:
              type: string
            phone:
              type: string
            locale:
              type: string
            given_name:
              type: string
            family_name:
              type: string
            user-agent:
              type: string
            accept-language:
              type: string
          description: User information
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentFlat'
          description: Uploaded files
        signatures:
          type: object
          description: Signature data
        files:
          type: object
          description: Organized files by category
    AttachmentFlat:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Attachment UUID
        name:
          type: string
          description: Original filename
        type:
          type: string
          description: MIME type
        scope:
          type: string
          nullable: true
          description: Attachment scope
        data:
          type: string
          nullable: true
          description: Base64-encoded file content
        metadata:
          type: object
          properties:
            size:
              type: integer
              description: File size in bytes
            width:
              type: integer
              nullable: true
            height:
              type: integer
              nullable: true
        uri:
          type: string
          format: uri
          description: Direct download URL
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        API token (starts with pnbx_). Create at
        https://app.penbox.io/workspace/settings/api. Include as: Authorization:
        Bearer {token}

````