Manage Contacts

Use this guide when you need to create and search contacts, attach funding sources (bank or virtual account), send funding source links so a contact can add their bank details, import contacts in bulk, and read virtual account balances. The same APIs power internal rails when contacts are typed SELF or VIRTUAL_ACCOUNT.

Prerequisites

• Authentication: API key via x-api-key / X-API-Key — see Authenticating API requests (same for Payment Center and Transfer Center).
• Base URL: Production https://api.swirepay.com (see API reference for staging if applicable).

1. Contacts (CRUD and search)

1. Create a contact with name, phone, email, contactType (for example VENDOR, CUSTOMER, SELF, VIRTUAL_ACCOUNT), optional meta, and address.
2. List and search using query parameters on the list endpoint (filter by name, type, pagination).
3. Get or delete a single contact by gid.

API reference:

• Create Contact
• Get All Contacts
• Get Contact by GID
• Delete Contact

2. Custom contact types (suggestions)

If you use custom type strings, list or remove entries stored as custom suggestions.

• Get Custom Contact Types
• Delete All Custom Contact Types
• Delete Specific Custom Contact Type

3. Funding sources

A funding source ties a contact to a bank rail. The resource can represent either:

• Issuer bank (sourceType: ISSUER_BANK, with issuerBank populated), or
• Virtual account (sourceType: VIRTUAL_ACCOUNT, with virtualAccount populated).

Create or list funding sources after the contact exists; use contactGid in the create body as required by your integration.

• Get Funding Sources
• Create Funding Source
• Get Funding Source by GID
• Delete Funding Source

4. Funding source links (invite flow)

Use a funding source link when the contact should self-serve their bank details (hosted link, optional notificationType for delivery).

Single contact:

• Add Funding Source Link
• Get Funding Source Link by GID
• Add Funding Source into Link

Bulk (existing contacts, JSON array — no Excel):

• Bulk Add Funding Source Links

Bulk (Excel — create contacts + send links): see Bulk Upload.

5. Virtual accounts and balances

Virtual accounts are exposed as first-class objects. List accounts; each item includes lastUpdatedBalance, balanceUpdatedAt, and alertThreshold (and related fields) so you can surface holdings next to a contact or treasury view without a separate balance call.

• Get Virtual Accounts

6. Bulk upload (Excel)

For large imports (contacts + funding source links, or direct funding sources with bank details), follow the dedicated guide:

• Bulk Upload

Common pitfalls

• Validation: List/create bodies must satisfy schema rules; invalid phone or email patterns may return error envelopes.
• Async work: Some downstream verification shows up on the contact or funding source status—poll or use webhooks for updates.

Next: send money with Send Money to Contact.