Create your first request

Use our API reference to create you first Penbox request. You will be able to make an API call on CONNECT by putting the token in the authentication section.

This API endpoint is used to create a Penbox request that will be sent to the person of your choice.

Checkpoints

👍

At this stage you should already have a generated token.

For further information please go to 'Get your credentials'.

Use our API reference to create a request

1. Go to CREATE a request
2. Paste your generated token in the Authentication section
3. Select 'Examples' and choose the option 'Example Integration Guide'
4. Select 'Try It' to create your request

👍

Congratulations you created your first request, it's that easy!

Explanations

Hostname and headers

User object

In the example generated above the user email and user phone are not pre-filled. If you would like to generate a Penbox request with a notification to the user by email or phone you can fill the email and/or phone attribute in the user object.

Data object

In the data object you can fill the following attributes to include this information in the Penbox request. This is an optional step but it's highly recommended to pre-fill already known data in the Penbox flow that is sent to the customer. Having certain information pre-filled reassures the customer and makes it easier for them to complete the flow.

"data": {
    "address_street": "station street",
    "address_number": "100",
    "address_zip": "1000",
    "address_city": "Brussels"
  }

Flow object

In the flow object you can find the slug attribute. This attribute is used to determine which Penbox flow you would like to use in your request. This is an attribute that is mandatory.
In this integration example the slug "demo-update' has been pre-filled to use the flow "Demo customer data update" flow.

"flow": {
    "slug": "demo-update"
  }

Options object

You can use the options object to parameter your flow. In this example you can choose to ask a legal document (e.g. ID document) in the request or not.

"options": {
    "ask_legal_documents": true
  }

External_args object

In the external_args object you can include parameters that will make it useful for you to process the data. All the attributes that you will put in external_args will be included in the exact same way when receiving the response of the request. Attributes in the external_args object can also be used to filter requests.
E.g: internal id, company id, etc.

 "external_args": {
    "company_id": "test001"
  }

Response payload

Here is an example of payload that you should receive as response and the explanation below.

{
  "id": "75d06157-75c7-4dc8-b090-e7064fd59544",
  "created_at": "2023-04-17T20:49:55.046Z",
  "status": "pending",
  "archived": false,
  "user": {
    "email": "[email protected]",
    "phone": "0484776960",
    "given_name": "Olivia",
    "family_name": "Peeters",
    "internal_ref": "internal_id_123456"
  },
  "external_args": {
    "company_id": "test001"
  },
  "flow": {
    "slug": "demo-update"
  },
  "links": {
    "fill": "https://form.superbroker.be/ddBhV3XHTciwkOcGT9WVRA",
    "app": "https://app.penbox.io/dev-box?id=75d06157-75c7-4dc8-b090-e7064fd59544"
  },
  "data": {
    "address_zip": "1000",
    "address_city": "Brussels",
    "address_number": "100",
    "address_street": "station street"
  },
  "options": {
    "ask_legal_documents": true
  },
  "responses": []
}

👍

Congrats you completed your first request! Keep your Response id nice and close because you will need it in the next step...