Update Recipient

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    mailing_list_id: 1,
    name: 'Tobias Example',
    company: 'thanks.io',
    address: '123 Main Street',
    address2: 'Apartment 1',
    city: 'Any Town',
    province: 'KS',
    postal_code: '12345',
    country: 'US',
    dob: '1981-04-23',
    anniversary: '2025-07-21',
    email: 'tobias@example.com',
    phone: '+1 (555) 123-4567',
    custom1: 'Unique Info',
    custom2: 'For example a product code or customer ID',
    custom3: 'Any Extra Info',
    custom4: 'Any Extra Info',
    custom5: 'Any Extra Info',
    custom6: 'Any Extra Info',
    custom7: 'Any Extra Info',
    custom8: 'Any Extra Info',
    custom9: 'Any Extra Info',
    custom10: 'Any Extra Info',
    absentee_address: '742 Evergreen Terrace, Springfield, IL 62704',
    absentee_city: 'Springfield',
    absentee_province: 'IL',
    absentee_postal_code: '62704'
  })
};

fetch('https://api.thanks.io/api/v2/recipients/{recipientId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request PUT \
  --url https://api.thanks.io/api/v2/recipients/{recipientId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mailing_list_id": 1,
  "name": "Tobias Example",
  "company": "thanks.io",
  "address": "123 Main Street",
  "address2": "Apartment 1",
  "city": "Any Town",
  "province": "KS",
  "postal_code": "12345",
  "country": "US",
  "dob": "1981-04-23",
  "anniversary": "2025-07-21",
  "email": "tobias@example.com",
  "phone": "+1 (555) 123-4567",
  "custom1": "Unique Info",
  "custom2": "For example a product code or customer ID",
  "custom3": "Any Extra Info",
  "custom4": "Any Extra Info",
  "custom5": "Any Extra Info",
  "custom6": "Any Extra Info",
  "custom7": "Any Extra Info",
  "custom8": "Any Extra Info",
  "custom9": "Any Extra Info",
  "custom10": "Any Extra Info",
  "absentee_address": "742 Evergreen Terrace, Springfield, IL 62704",
  "absentee_city": "Springfield",
  "absentee_province": "IL",
  "absentee_postal_code": "62704"
}
'

import requests

url = "https://api.thanks.io/api/v2/recipients/{recipientId}"

payload = {
    "mailing_list_id": 1,
    "name": "Tobias Example",
    "company": "thanks.io",
    "address": "123 Main Street",
    "address2": "Apartment 1",
    "city": "Any Town",
    "province": "KS",
    "postal_code": "12345",
    "country": "US",
    "dob": "1981-04-23",
    "anniversary": "2025-07-21",
    "email": "tobias@example.com",
    "phone": "+1 (555) 123-4567",
    "custom1": "Unique Info",
    "custom2": "For example a product code or customer ID",
    "custom3": "Any Extra Info",
    "custom4": "Any Extra Info",
    "custom5": "Any Extra Info",
    "custom6": "Any Extra Info",
    "custom7": "Any Extra Info",
    "custom8": "Any Extra Info",
    "custom9": "Any Extra Info",
    "custom10": "Any Extra Info",
    "absentee_address": "742 Evergreen Terrace, Springfield, IL 62704",
    "absentee_city": "Springfield",
    "absentee_province": "IL",
    "absentee_postal_code": "62704"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

{
  "id": 18113288,
  "mailing_list_id": 1,
  "name": "Tobias Example",
  "company": "thanks.io",
  "address": "12345 Main Street",
  "address2": "Apartment 1",
  "city": "Any Town",
  "province": "NY",
  "postal_code": "12345",
  "country": "US",
  "dob": "1981-04-23",
  "anniversary": "2025-07-21",
  "email": "tobias@example.com",
  "phone": "845-988-6485",
  "custom1": "Unique Info",
  "custom2": "For example a product code or customer ID",
  "custom3": "",
  "custom4": "",
  "created_at": "2025-06-27T14:57:11.000000Z",
  "updated_at": "2025-06-27T14:57:11.000000Z",
  "mailing_list": {
    "id": 1,
    "user_id": 2,
    "sub_account_id": null,
    "type": "manual",
    "description": "Sphere Contacts Mailing List",
    "qrcode_url": null,
    "total_recipients": 1,
    "processed": true,
    "is_suppression_list": false,
    "total_scans": 1,
    "unique_scans": 1,
    "last_scan": "2025-07-13T13:57:11.000000Z",
    "total_sends": 2,
    "last_send": "2025-07-06T13:57:11.000000Z",
    "created_at": "6 years ago",
    "updated_at": "2025-06-27T14:57:11.000000Z"
  }
}

Recipients

Update Recipient

Update details of a specific recipient by ID. Leave out absentee_address to keep the current absentee address. Sending it replaces the stored absentee address as a whole, so send it together with any of absentee_city, absentee_province and absentee_postal_code: those on their own, for example only a new ZIP, are refused with a 400 and nothing is updated. Send absentee_address as an empty string or null to remove the absentee address; if the same request also sets custom1 to absentee with an address in custom2, that address is copied in instead.

PUT

recipients

{recipientId}

Update Recipient

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    mailing_list_id: 1,
    name: 'Tobias Example',
    company: 'thanks.io',
    address: '123 Main Street',
    address2: 'Apartment 1',
    city: 'Any Town',
    province: 'KS',
    postal_code: '12345',
    country: 'US',
    dob: '1981-04-23',
    anniversary: '2025-07-21',
    email: 'tobias@example.com',
    phone: '+1 (555) 123-4567',
    custom1: 'Unique Info',
    custom2: 'For example a product code or customer ID',
    custom3: 'Any Extra Info',
    custom4: 'Any Extra Info',
    custom5: 'Any Extra Info',
    custom6: 'Any Extra Info',
    custom7: 'Any Extra Info',
    custom8: 'Any Extra Info',
    custom9: 'Any Extra Info',
    custom10: 'Any Extra Info',
    absentee_address: '742 Evergreen Terrace, Springfield, IL 62704',
    absentee_city: 'Springfield',
    absentee_province: 'IL',
    absentee_postal_code: '62704'
  })
};

fetch('https://api.thanks.io/api/v2/recipients/{recipientId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request PUT \
  --url https://api.thanks.io/api/v2/recipients/{recipientId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mailing_list_id": 1,
  "name": "Tobias Example",
  "company": "thanks.io",
  "address": "123 Main Street",
  "address2": "Apartment 1",
  "city": "Any Town",
  "province": "KS",
  "postal_code": "12345",
  "country": "US",
  "dob": "1981-04-23",
  "anniversary": "2025-07-21",
  "email": "tobias@example.com",
  "phone": "+1 (555) 123-4567",
  "custom1": "Unique Info",
  "custom2": "For example a product code or customer ID",
  "custom3": "Any Extra Info",
  "custom4": "Any Extra Info",
  "custom5": "Any Extra Info",
  "custom6": "Any Extra Info",
  "custom7": "Any Extra Info",
  "custom8": "Any Extra Info",
  "custom9": "Any Extra Info",
  "custom10": "Any Extra Info",
  "absentee_address": "742 Evergreen Terrace, Springfield, IL 62704",
  "absentee_city": "Springfield",
  "absentee_province": "IL",
  "absentee_postal_code": "62704"
}
'

import requests

url = "https://api.thanks.io/api/v2/recipients/{recipientId}"

payload = {
    "mailing_list_id": 1,
    "name": "Tobias Example",
    "company": "thanks.io",
    "address": "123 Main Street",
    "address2": "Apartment 1",
    "city": "Any Town",
    "province": "KS",
    "postal_code": "12345",
    "country": "US",
    "dob": "1981-04-23",
    "anniversary": "2025-07-21",
    "email": "tobias@example.com",
    "phone": "+1 (555) 123-4567",
    "custom1": "Unique Info",
    "custom2": "For example a product code or customer ID",
    "custom3": "Any Extra Info",
    "custom4": "Any Extra Info",
    "custom5": "Any Extra Info",
    "custom6": "Any Extra Info",
    "custom7": "Any Extra Info",
    "custom8": "Any Extra Info",
    "custom9": "Any Extra Info",
    "custom10": "Any Extra Info",
    "absentee_address": "742 Evergreen Terrace, Springfield, IL 62704",
    "absentee_city": "Springfield",
    "absentee_province": "IL",
    "absentee_postal_code": "62704"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

{
  "id": 18113288,
  "mailing_list_id": 1,
  "name": "Tobias Example",
  "company": "thanks.io",
  "address": "12345 Main Street",
  "address2": "Apartment 1",
  "city": "Any Town",
  "province": "NY",
  "postal_code": "12345",
  "country": "US",
  "dob": "1981-04-23",
  "anniversary": "2025-07-21",
  "email": "tobias@example.com",
  "phone": "845-988-6485",
  "custom1": "Unique Info",
  "custom2": "For example a product code or customer ID",
  "custom3": "",
  "custom4": "",
  "created_at": "2025-06-27T14:57:11.000000Z",
  "updated_at": "2025-06-27T14:57:11.000000Z",
  "mailing_list": {
    "id": 1,
    "user_id": 2,
    "sub_account_id": null,
    "type": "manual",
    "description": "Sphere Contacts Mailing List",
    "qrcode_url": null,
    "total_recipients": 1,
    "processed": true,
    "is_suppression_list": false,
    "total_scans": 1,
    "unique_scans": 1,
    "last_scan": "2025-07-13T13:57:11.000000Z",
    "total_sends": 2,
    "last_send": "2025-07-06T13:57:11.000000Z",
    "created_at": "6 years ago",
    "updated_at": "2025-06-27T14:57:11.000000Z"
  }
}

Authorizations

Authorization

string

header

required

Bearer token authentication using your thanks.io API key

Path Parameters

recipientId

integer

required

Recipient ID

Example:

296446

Body

application/json

mailing_list_id

integer

Example:

1

name

string

Example:

"Tobias Example"

company

string

Example:

"thanks.io"

address

string

Example:

"123 Main Street"

address2

string

Example:

"Apartment 1"

city

string

Example:

"Any Town"

province

string

State or Province

Example:

"KS"

postal_code

string

Example:

"12345"

country

string

Example:

"US"

dob

string

Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.

Example:

"1981-04-23"

anniversary

string

Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.

Example:

"2025-07-21"

string

Example:

"tobias@example.com"

phone

string

Example:

"+1 (555) 123-4567"

custom1

string

Custom field for additional information about the recipient

Example:

"Unique Info"

custom2

string

Custom field for additional information about the recipient

Example:

"For example a product code or customer ID"

custom3

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom4

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom5

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom6

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom7

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom8

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom9

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom10

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

absentee_address

string | null

The property (absentee) address the absentee image template and message variables use, or null when none is set. Mail is delivered to address, not here.

Example:

"742 Evergreen Terrace, Springfield, IL 62704"

absentee_city

string

City of the absentee (property) address. Requires absentee_address in the same request.

Example:

"Springfield"

absentee_province

string

State or province of the absentee (property) address. Requires absentee_address in the same request.

Example:

"IL"

absentee_postal_code

string

ZIP or postal code of the absentee (property) address. Requires absentee_address in the same request.

Example:

"62704"

Response

Successful Response

integer

read-only

Example:

18113288

mailing_list_id

integer

Example:

1

name

string

Example:

"Tobias Example"

company

string

Example:

"thanks.io"

address

string

Example:

"123 Main Street"

address2

string

Example:

"Apartment 1"

city

string

Example:

"Any Town"

province

string

State or Province

Example:

"KS"

postal_code

string

Example:

"12345"

country

string

Example:

"US"

dob

string

Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.

Example:

"1981-04-23"

anniversary

string

Example:

"2025-07-21"

string

Example:

"tobias@example.com"

phone

string

Example:

"+1 (555) 123-4567"

custom1

string

Custom field for additional information about the recipient

Example:

"Unique Info"

custom2

string

Custom field for additional information about the recipient

Example:

"For example a product code or customer ID"

custom3

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom4

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom5

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom6

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom7

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom8

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom9

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom10

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

absentee_address

string | null

The property (absentee) address the absentee image template and message variables use, or null when none is set. Mail is delivered to address, not here.

Example:

"742 Evergreen Terrace, Springfield, IL 62704"

mailing-list

object

The mailing list this recipient belongs to

Show child attributes

created_at

string

read-only

Example:

"2025-06-27T14:57:11.000000Z"

updated_at

string

read-only

Example:

"2025-06-27T14:57:11.000000Z"

Get Started

Authentication

API Endpoints

Examples

Update Recipient

Authorizations

Path Parameters

Body

Response