Contacts | Paid | Documentation

The Contact Object

1 class Contact
2   attr_accessor :id, :organization_id, :account_id, :salutation, :first_name,
3                 :last_name, :email, :phone, :billing_street, :billing_city,
4                 :billing_state_province, :billing_country, :billing_zip_postal_code,
5                 :external_id, :account_name # Read-only field set by server
6 end
7 
8 module Salutation
9   MR = "Mr."
10   MRS = "Mrs." 
11   MISS = "Miss."
12   MS = "Ms."
13   DR = "Dr."
14   PROF = "Prof."
15 end

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the contact
`organization_id`	string	Organization ID the contact belongs to
`account_id`	string	ID of the account this contact belongs to
`salutation`	string	Contact’s salutation (e.g., Mr., Mrs., Dr.)
`first_name`	string	Contact’s first name
`last_name`	string	Contact’s last name
`email`	string	Contact’s email address
`phone`	string	Optional phone number
`billing_street`	string	Billing street address
`billing_city`	string	Billing city
`billing_state_province`	string	Billing state or province
`billing_country`	string	Billing country
`billing_postal_code`	string	Billing ZIP or postal code
`external_id`	string	External custom ID for the contact
`account_name`	string	Read-only field containing the associated account’s name

API Endpoints

Create a Contact

Creates a new contact with given data.

SDK Functions

Ruby

1 require 'paid_ruby'
2 
3 # Initialize the client
4 api = Paid::Client.new(
5     token: "YOUR-API-KEY"
6 )
7 
8 # Create the contact
9 contact = api.contacts.create(
10     first_name: "John",
11     last_name: "Doe",
12     salutation: Paid::Salutation::MR,
13     email: "john.doe@acme.com",
14     phone: "+1-555-0123",
15     billing_street: "123 Main St",
16     billing_city: "San Francisco",
17     billing_state_province: "CA",
18     billing_country: "USA",
19     billing_postal_code: "94105",
20     external_id: "acme_contact_123",
21     customer_external_id: customer_external_id, # use either customer_id or customer_external_id for contact creation
22 )

Returns

Returns the Contact object upon successful creation. It’s recommended to store the returned contact ID in your own system for future reference and operations.

1 {
2   "id": "uuid",
3   "organization_id": "uuid", 
4   "salutation": "Mr.",
5   "first_name": "John",
6   "last_name": "Doe",
7   "account_name": "Acme Ltd",
8   "email": "john.doe@acme.com",
9   "phone": "+1-555-0123",
10   "billing_street": "123 Main St",
11   "billing_city": "San Francisco", 
12   "billing_state_province": "CA",
13   "billing_country": "USA",
14   "billing_postal_code": "94105",
15   "external_id": "acme_contact_123",
16   "account_id": "uuid"
17 }

Retrieve a Contact

Retrieves a contact by its internal ID.

SDK Functions

Ruby

1 # Retrieve contact by its internal ID
2 contact = api.contacts.get(contact_id: id)
3 
4 # Retrieve contact by its external ID
5 contact = api.contacts.get_by_external_id(external_id: id)

Returns

Returns the up-to-date Contact object for a valid identifier. Raises an error if parameters are invalid (e.g. specifying an invalid internal contact ID)

1 {
2   "id": "uuid",
3   "organization_id": "uuid", 
4   "salutation": "Mr.",
5   "first_name": "John",
6   "last_name": "Doe",
7   "account_name": "Acme Ltd",
8   "email": "john.doe@acme.com",
9   "phone": "+1-555-0123",
10   "billing_street": "123 Main St",
11   "billing_city": "San Francisco", 
12   "billing_state_province": "CA",
13   "billing_country": "USA",
14   "billing_postal_code": "94105",
15   "external_id": "acme_contact_123",
16   "account_id": "uuid"
17 }

List all Contacts

Retrieves all contacts associated with your organization.

Ruby

1 # List all contacts
2 contacts = api.contacts.list()

Returns

Returns the up-to-date list of Contact objects.

1 [
2 	{
3 	    id: 'uuid',
4 		organization_id: 'uuid',
5   		salutation: 'Mr.',
6   		first_name: 'John',
7   		last_name: 'Doe',
8   		...
9 	},
10 	{
11 	    id: 'uuid',
12 		organization_id: 'uuid',
13   		salutation: 'Ms.',
14   		first_name: 'Jane',
15   		last_name: 'Doe',
16   		...
17 	}
18 ]

Delete a Contact

Deletes a contact by its internal ID.

SDK Functions

Ruby

1 # Delete contact by its internal ID
2 api.contacts.delete(contact_id: id)
3 
4 # Delete contact by its external ID
5 api.contacts.delete_by_external_id(external_id: id)

Returns

This is a void function. It performs the requested operation but does not return any value upon success. If the contact ID does not exist, this call raises an error.

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests:

2xx range indicates success
4xx range indicates an error that failed given the information provided
5xx range indicates an error with Paid’s servers

Error Response Format

1 {
2   "error": {
3     "message": "Error message",
4     "code": "ERROR_CODE",
5     "details": "Additional error details"
6   }
7 }

Common Error Codes

Code	Description
`CONTACT_NOT_FOUND`	The specified contact does not exist
`INVALID_REQUEST`	The request was invalid
`UNAUTHORIZED`	The API key is invalid
`FORBIDDEN`	The API key doesn’t have permission to access the resource
`INTERNAL_SERVER_ERROR`	An error occurred on Paid’s servers