Get Form Response

Get Response

curl --request GET \
  --url https://connect.penbox.io/v1/responses/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://connect.penbox.io/v1/responses/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://connect.penbox.io/v1/responses/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.penbox.io/v1/responses/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://connect.penbox.io/v1/responses/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "completed_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "data": {},
  "user": {
    "anonymous": true,
    "ip": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "locale": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "user-agent": "<string>",
    "accept-language": "<string>"
  },
  "attachments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "type": "<string>",
      "scope": "<string>",
      "data": "<string>",
      "metadata": {
        "size": 123,
        "width": 123,
        "height": 123
      },
      "uri": "<string>"
    }
  ],
  "signatures": {},
  "files": {}
}

GET

responses

{id}

Get Response

curl --request GET \
  --url https://connect.penbox.io/v1/responses/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://connect.penbox.io/v1/responses/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://connect.penbox.io/v1/responses/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.penbox.io/v1/responses/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://connect.penbox.io/v1/responses/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "completed_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "data": {},
  "user": {
    "anonymous": true,
    "ip": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "locale": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "user-agent": "<string>",
    "accept-language": "<string>"
  },
  "attachments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "type": "<string>",
      "scope": "<string>",
      "data": "<string>",
      "metadata": {
        "size": 123,
        "width": 123,
        "height": 123
      },
      "uri": "<string>"
    }
  ],
  "signatures": {},
  "files": {}
}

Retrieve complete form response data including answers and attachments.

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

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:

// 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:

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:

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

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

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

Authorizations

Authorization

string

header

required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Headers

enum<string>

Response format: application/json or application/pdf

Available options:

application/json,

application/pdf

Path Parameters

string<uuid>

required

Response UUID

Response

Successful response

Detailed response with all nested data

string<uuid>

Response UUID

completed_at

string<date-time> | null

Timestamp when the response was completed

updated_at

string<date-time>

Last update timestamp

data

object

Form field values

user

object

User information

Show child attributes

attachments

object[]

Uploaded files

Show child attributes

signatures

object

Signature data

files

object

Organized files by category

API Reference

Workspaces

Cases

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Response Formats

Response Fields

Response Attributes

User Object

Completion Status

Finding Response IDs

Accessing Form Data

Working with Uploaded Files

Response Codes

Authorizations

Headers

Path Parameters

Response

​Response Formats

​Response Fields

​Response Attributes

​User Object

​Completion Status

​Finding Response IDs

​Accessing Form Data

​Working with Uploaded Files

​Response Codes

Authorizations

Headers

Path Parameters

Response

Response Formats

Response Fields

Response Attributes

User Object

Completion Status

Finding Response IDs

Accessing Form Data

Working with Uploaded Files

Response Codes