> ## Documentation Index > Fetch the complete documentation index at: https://pay3.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Contacts API — List, Create, and Delete Recipients > Manage your trusted Stellar recipient contacts via the Pay3 API. List, create, and delete contacts used for AI payment resolution by name or alias. Contacts are your saved Stellar recipients — the trusted addresses your AI agents resolve by name when initiating transfers. Instead of requiring a raw Stellar address on every payment instruction, you can register a contact with a human-readable `alias` (e.g. `alice`) and let Pay3's AI resolve it automatically at transaction time. This page documents all three contact management endpoints: listing your existing contacts, creating a new one, and deleting one you no longer need. ## Authentication All requests must include a valid bearer token in the `Authorization` header, or a `pay3_session` cookie obtained during wallet authentication. ``` Authorization: Bearer ``` *** ## GET /api/contacts Retrieve the full list of contacts saved to your account. Contacts are returned in ascending alphabetical order by `displayName`. ### Endpoint ``` GET /api/contacts ``` ### Response fields **id** `string` *required* Unique UUID identifying this contact. **displayName** `string` *required* Human-readable name for the contact (e.g. `"Alice Johnson"`). **alias** `string` Short identifier used by the AI to resolve this recipient by name (e.g. `"alice"`). May be `null` if no alias was set at creation. **stellarAddress** `string` *required* The contact's Stellar public key (G-address), stored in uppercase. **verifiedAt** `string` *required* ISO 8601 timestamp marking when the contact was verified. Set to the creation time automatically. **createdAt** `string` *required* ISO 8601 timestamp when the contact was created. **updatedAt** `string` *required* ISO 8601 timestamp when the contact was last modified. ### Example request ```bash theme={null} curl https://api.pay3.dev/api/contacts \ -H "Authorization: Bearer " ``` ### Example response ```json theme={null} [ { "id": "c1a2b3d4-0001-4abc-8def-000000000001", "displayName": "Alice Johnson", "alias": "alice", "stellarAddress": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37", "verifiedAt": "2025-06-01T10:00:00.000Z", "createdAt": "2025-06-01T10:00:00.000Z", "updatedAt": "2025-06-01T10:00:00.000Z" }, { "id": "c1a2b3d4-0002-4abc-8def-000000000002", "displayName": "Bob Smith", "alias": "bob", "stellarAddress": "GBVFEQKQ5VGHIH4CVXOL5TXIVMS6OJQMQHM5LLNTV3AAJHID5OFWKM4", "verifiedAt": "2025-06-15T08:30:00.000Z", "createdAt": "2025-06-15T08:30:00.000Z", "updatedAt": "2025-06-15T08:30:00.000Z" } ] ``` *** ## POST /api/contacts Create a new contact and associate it with your account. The `stellarAddress` is normalized to uppercase on save, and `verifiedAt` is set automatically to the time of creation. Returns `201 Created` with the new contact object. ### Endpoint ``` POST /api/contacts ``` ### Request body **displayName** `string` *required* Full human-readable name for the contact (e.g. `"Alice Johnson"`). Leading and trailing whitespace is stripped automatically. **alias** `string` Short identifier used by the Pay3 AI to resolve this recipient by name during payment instructions (e.g. `"alice"`). Must be unique across all your contacts. Omit to leave the alias unset. **stellarAddress** `string` *required* The contact's Stellar public key (G-address). Whitespace is stripped and the value is converted to uppercase before storage. > [!NOTE] > > The `alias` field must be **unique** across all your contacts. When an AI agent receives a natural-language instruction like *"send 50 USDC to alice"*, Pay3 resolves the recipient by matching `alias` against your contact list. Duplicate aliases will cause resolution to fail. ### Response fields **id** `string` *required* Unique UUID assigned to the newly created contact. **displayName** `string` *required* The display name as stored (whitespace trimmed). **alias** `string` The alias as stored, or `null` if none was provided. **stellarAddress** `string` *required* The Stellar G-address, normalized to uppercase. **verifiedAt** `string` *required* ISO 8601 timestamp marking when the contact was verified. Set to the creation time automatically. **createdAt** `string` *required* ISO 8601 timestamp when the contact record was created. **updatedAt** `string` *required* ISO 8601 timestamp when the contact was last modified. Equals `createdAt` on creation. ### Error responses | Status | Meaning | | - | - | | `400 Bad Request` | Missing `displayName` or `stellarAddress`, or a duplicate `alias` already exists on your account. | | `401 Unauthorized` | Missing or invalid bearer token. | | `409 Conflict` | A contact with the same `stellarAddress` already exists on your account. | ### Example request ```bash theme={null} curl -X POST https://api.pay3.dev/api/contacts \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "displayName": "Alice Johnson", "alias": "alice", "stellarAddress": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37" }' ``` ### Example response ```json theme={null} { "id": "c1a2b3d4-0001-4abc-8def-000000000001", "displayName": "Alice Johnson", "alias": "alice", "stellarAddress": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37", "verifiedAt": "2025-07-08T14:30:00.000Z", "createdAt": "2025-07-08T14:30:00.000Z", "updatedAt": "2025-07-08T14:30:00.000Z" } ``` *** ## DELETE /api/contacts/:id Permanently delete a contact from your account by its UUID. This action is irreversible — the contact record is removed immediately and cannot be recovered. Returns HTTP `204 No Content` on success. ### Endpoint ``` DELETE /api/contacts/:id ``` ### Path parameters **id** `string` *required* The UUID of the contact to delete. You can only delete contacts belonging to your own account. > [!WARNING] > > If a contact's `id` appears in a policy's `allowedRecipientIds` list, deleting the contact does **not** automatically remove it from that list. Any active AI session governed by that policy will continue to reference the now-deleted contact ID. Update the affected policies after deleting a contact to keep your recipient restrictions accurate. ### Response Returns HTTP `204 No Content` on success — no response body is sent. ### Error responses | Status | Meaning | | - | - | | `400 Bad Request` | The provided `id` is not a valid UUID. | | `401 Unauthorized` | Missing or invalid bearer token. | | `404 Not Found` | No contact exists for the given `id` on your account. | ### Example request ```bash theme={null} curl -X DELETE https://api.pay3.dev/api/contacts/c1a2b3d4-0001-4abc-8def-000000000001 \ -H "Authorization: Bearer " ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.