Contacts

Contacts are people at the customer’s organization associated with a Billabex account. They receive payment reminders and other communications from the dunning agent.

Overview

When Billabex’s dunning agent sends payment reminders, it needs to know who to contact at the customer’s organization. Contacts provide that information.

Contact Properties

Email Status

The email object contains the address and its validation status:

{
  "address": "john@acme.com",
  "status": "Valid"
}

Possible status values:

Email status is read-only and updated automatically based on delivery results.

API Endpoints

Creating a Contact

const response = await fetch('[baseURL]/api/public/v1/accounts/ACCOUNT_ID/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fullName: 'John Smith',
    email: 'john.smith@acme.com',
    language: 'en',
  }),
});

const contact = await response.json();

Using cURL

curl -X POST "[baseURL]/api/public/v1/accounts/ACCOUNT_ID/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "John Smith",
    "email": "john.smith@acme.com",
    "language": "en"
  }'

Required Fields

Updating a Contact

Use PATCH to update specific fields:

const response = await fetch('[baseURL]/api/public/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fullName: 'John A. Smith',
  }),
});

Only the provided fields will be updated.

Listing Contacts

const response = await fetch('[baseURL]/api/public/v1/accounts/ACCOUNT_ID/contacts?first=10', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

const data = await response.json();
// data.nodes contains the contacts array
// data.pageInfo contains pagination info

Deleting a Contact

const response = await fetch('[baseURL]/api/public/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

// Returns 204 No Content on success

Language

The language field determines which language Billabex uses when communicating with the contact. Use ISO 639-1 two-letter codes:

The dunning agent automatically translates payment reminders to the contact’s preferred language.

Using Upsert for Sync

When synchronizing contacts from external systems, use the upsert endpoints to simplify your logic:

// Sync contacts from your CRM
for (const crmContact of crmContacts) {
  await fetch(`[baseURL]/api/public/v1/accounts/${crmContact.billabexAccountId}/contacts/upsert`, {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      fullName: crmContact.name,
      email: crmContact.email,
      language: crmContact.preferredLanguage || 'en',
    }),
  });
}

See the Upsert Operations guide for details on matching logic.

Best Practices

Set Correct Languages

Accurate language settings ensure customers receive communications they can understand:

// Match the contact's actual language preference
"language": "fr"  // For French-speaking contacts

Handle Email Bounces

Monitor the email.status field and update contacts when emails bounce:

if (contact.email?.status === 'Bounced') {
  // Alert your team to update the contact's email
  // Or automatically mark as needing attention
}

Next Steps

• Upsert Operations – Create or update in one request
• Account Sources – Link accounts to external systems
• Getting Started – API basics
• API Reference – Full endpoint documentation

Support

Questions about managing contacts?
Contact us via the website contact form.