Create a contact

8 min

Every payment in Jetpay starts with a contact. Creating a contact is a foundational part of using the platform. It’s how you organize your customers and associate their payment methods, making all subsequent flows possible.

Prerequisites

Jetpay API KeyAPI token

Flow

Adding a contact is done via a single call to the Create Contact endpoint.

This will respond back with the new contact information including it's UUID.

sequenceDiagram
    participant partner as Platform
    participant api as Jetpay

    partner->>+api: Create new contact.
    Note right of api: PUT /contact

    api-->>-partner: R: Contact created.
    Note right of api: 200 OK

Implementation details

Create a Contact

Endpoint: PUT /contact

curl https://extapi.demo.jetpay.baselinepayments.com/contact \
  -X PUT \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Smith",
    "tags": [],
    "language": "en"
  }'

The tags field is for you to use to help you sort your contacts into certain categories. The default tags that Jetpay supports are customer and supplier, however, you can create any custom tag. For example, you can use a tag to specify what region your contact is created for, like North America.

The language field determines what language we will send communication emails to the customer in. For most API integrations, you will likely want emails disabled, and handle your own communications with customers. The options are en for English or fr for French. If no language is specified, the default value will be en.

Handle the response

If a Contact is successfully created, a response will be returned with an HTTP status code of 200, and a response body of:

{
  "identifier": "contact_123",
  "email": "[email protected]",
  "name": "John Smith",
  "tags": [],
  "contact_type": "customer",
  "language": "en"
}

The default contact_type is customer. It is only if you specify the supplier tag in the tags list that the type will be set to supplier. Functionally, contact_type will not affect API behaviour.

Common errors

If you try to create a contact with the same email as an existing contact, we will return an HTTP status code of 409, and a response body of:

{"message":"A contact with the same email address has already been created."}