Contacts Endpoint

The Contacts feature allows your integration to neatly organization transactions, account vault data, recurring payments, and quick invoices by customer.  This is beneficial for solutions that allow a customer to store multiple payment types and maybe looking to reference customer within there ecosystem.  Below, you will find information on the available endpoint actions, fields, requirements, and responses for the Contacts Endpoint. These samples include the initial request and response that is expected when building out your integration.

.

Endpoint Actions

Create Record

POST /v2/contacts

{
    "contact": {
        "location_id": "123456789012345678901234",
        "account_number": "1234",
        "contact_api_id": "137",
        "first_name": "John",
        "last_name": "Smith",
        "cell_phone": "1234567890",
        "contact_balance": "245.65"
    }
}
{
    "contact": {
        "id": "123456789012345678901234",
        "location_id": "123456789012345678901234",
        "account_number": "1234",
        "contact_api_id": "137",
        "company_name": null,
        "first_name": "John",
        "last_name": "Smith",
        "email": null,
        "address": null,
        "city": null,
        "zip": null,
        "home_phone": null,
        "cell_phone": "1234567890",
        "office_phone": null,
        "office_ext_phone": null,
        "contact_balance": "245.65",
        "email_trx_receipt": false,
        "created_ts": 1421870788,
        "modified_ts": null,
        "date_of_birth": null,
        "header_message": null,
        "header_message_type": 0,
        "_links": {
            "self": {
                "href": "https://{url}/v2/contacts/123456789012345678901234"
            }
        }
    }
}

Update Record

PUT /v2/contacts/{id}

{
    "contact": {
        "cell_phone": "0987654321"
    }
}
{
    "contact": {
        "id": "123456789012345678901234",
        "location_id": "123456789012345678901234",
        "account_number": "1234",
        "contact_api_id": "137",
        "company_name": null,
        "first_name": "John",
        "last_name": "Smith",
        "email": null,
        "address": null,
        "city": null,
        "zip": null,
        "home_phone": null,
        "cell_phone": "0987654321",
        "office_phone": null,
        "office_ext_phone": null,
        "contact_balance": "245.65",
        "email_trx_receipt": false,
        "created_ts": 1421870788,
        "modified_ts": null,
        "date_of_birth": null,
        "header_message": null,
        "header_message_type": 0,
        "_links": {
            "self": {
                "href": "https://{url}/v2/contacts/123456789012345678901234"
            }
        }
    }
}

View Single Record

GET /v2/contacts/{id}

{
    // Empty Payload - Nothing Needed Here
}
{
    "contact": {
        "id": "123456789012345678901234",
        "location_id": "123456789012345678901234",
        "account_number": "1234",
        "contact_api_id": "137",
        "company_name": null,
        "first_name": "John",
        "last_name": "Smith",
        "email": null,
        "address": null,
        "city": null,
        "zip": null,
        "home_phone": null,
        "cell_phone": "0987654321",
        "office_phone": null,
        "office_ext_phone": null,
        "contact_balance": "245.65",
        "email_trx_receipt": false,
        "created_ts": 1421870788,
        "modified_ts": null,
        "date_of_birth": null,
        "header_message": null,
        "header_message_type": 0,
        "_links": {
            "self": {
                "href": "https://{url}/v2/contacts/123456789012345678901234"
            }
        }
    }
}

View Record List

GET /v2/contacts

Note: Filters can be used to search for Contacts by including the columns you want to filter on as URL parameters. for example /v2/contacts?field=value&field2=value2

{
    // Empty Payload - Nothing Needed Here
}
{
    "contacts": [
        {
            "id": "123456789012345678901234",
            "location_id": "123456789012345678901234",
            "account_number": "1234",
            "contact_api_id": "137",
            "company_name": null,
            "first_name": "John",
            "last_name": "Smith",
            "email": null,
            "address": null,
            "city": null,
            "zip": null,
            "home_phone": null,
            "cell_phone": "2485551111",
            "office_phone": null,
            "office_ext_phone": null,
            "contact_balance": "245.65",
            "email_trx_receipt": false,
            "created_ts": 1421870788,
            "modified_ts": null,
            "date_of_birth": null,
            "header_message": null,
            "header_message_type": 0,
            "_links": {
                "self": {
                    "href": "{url}/v2/contacts/123456789012345678901234"
                }
            }
        },
        ... // Other Contact Records
 
        {
            "id": "123456789012345678901235",
            "location_id": "123456789012345678901234",
            "account_number": "9876",
            "contact_api_id": "654",
            "company_name": null,
            "first_name": "Billy",
            "last_name": "Bob",
            "email": null,
            "address": null,
            "city": null,
            "zip": null,
            "home_phone": null,
            "cell_phone": "3135558585",
            "office_phone": null,
            "office_ext_phone": null,
            "contact_balance": null,
            "email_trx_receipt": false,
            "created_ts": 1421870338,
            "modified_ts": null,
            "date_of_birth": null,
            "header_message": null,
            "header_message_type": 0,
            "_links": {
                "self": {
                    "href": "{url}/v2/contacts/123456789012345678901235"
                }
            }
        }
    ],
    "meta": {
        "pagination": {
            "links": {
                "self": {
                    "href": "{url}/v2/contacts?field=value&field2=value2&sort=-created&page=1"
                },
                "next": {
                    "href": "{url}/v2/contacts?field=value&field2=value2&sort=-created&page=2"
                },
                "last": {
                    "href": "{url}/v2/contacts?field=value&field2=value2&sort=-created&page=11"
                }
            },
            "totalCount": 220,
            "pageCount": 11,
            "currentPage": 0,
            "perPage": 20
        },
        "sort": {
            "attributes": {
                "created": "desc"
            }
        }
    }
}

Delete Record

DELETE /v2/contacts/{id}

{
    // Empty Payload - Nothing Needed Here
}
No JSON response provided.  HTTP Response Code only.

204 - Success, Contact was deleted.
404 - Fail, Contact not found.

 

Fields

Name Min Max Format POST Required POST Allowed PUT Allowed Comments
id 24 36 string       System generated id
account_number 0 32 string   Contacts account number for bookkeeping
address 0 255 string   Address of contact
cell_phone 10 10 string   Cell phone of contact
city 0 100 string   City of contact
company_name 0 64 string   Company name of contact if applicable
contact_api_id 0 36 string   Contacts unique id used by API clients. This field is required if update_if_exists is set to '1'. This field can be used to correlate Contacts in our system to data within an outside software integration. In addition, when running a transaction, this value can be used in place of contact_id in order to associate the transaction with a contact.
contact_balance 0 12 string   Can be used to maintain a balance for the contact.
contact_c1 0 128 string   Custom field 1 for api users to store custom data
contact_c2 0 128 string   Custom field 2 for api users to store custom data
contact_c3 0 128 string   Custom field 3 for api users to store custom data
created_ts 10 10 integer       System created timestamp
date_of_birth 10 10 yyyy-mm-dd   Contacts DOB
email 5 64 string   Contacts email
email_trx_receipt 1 1 string   Whether or not to email all transactions receipts to contact (1 or 0)
first_name 0 64 string   Contacts first name
header_message 0 250 string   Header message to display in user interface
header_message_type 0 1 integer   header message type (0 = popup, 1-4 = colored banners)
home_phone 10 10 string   Contacts home phone
last_name 1 64 string Contacts last name
location_id 24 36 string   Location id the contact belongs to
modified_ts 10 10 integer       System modified timestamp
office_ext_phone 0 10 string   Optional phone extension for office phone
office_phone 10 10 string   Contacts office phone
state 2 2 string   Contacts valid two character state (e.g. MI, OH, NY)
update_if_exists 1 1 integer     Allows for updating of contacts using the POST method. If this field is set to '1' when POSTing, the contact will be updated (instead of returning 422 error) if it already exists.
zip 4 12 string   Alphanumeric, spaces, and dashes to accomodate domestic and international posyal codes

 

Expands (Related Records)

For detail on how to use Expands on an endpoint, please visit the Expands (Related Records) page.

Related Record Filter Name
Created User created_user
Notes notes
Location location
User user

 

An example of “expanding” this endpoint to one of the above related records would look like this:

GET /v2/contacts/xxxxxxxxxxxxxxxxxxxxxxxx?expand=created_user

To use multiple expands on this endpoint, simply include them both separated by a comma like so:

GET /v2/contacts/xxxxxxxxxxxxxxxxxxxxxxxx?expand=created_user,notes