recipient-create

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/thanks-io/json-schema/thanks-io-recipient-create-schema.json",
  "title": "recipient-create",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/thanks-io-openapi.json#/components/schemas/recipient-create",
  "type": "object",
  "anyOf": [
    {
      "title": "Create Recipient by Address",
      "description": "Create a recipient by providing address details",
      "required": [
        "mailing_list_id",
        "address"
      ]
    },
    {
      "title": "Create Recipient by Email",
      "description": "Create a recipient by providing email address",
      "required": [
        "mailing_list_id",
        "email"
      ]
    }
  ],
  "properties": {
    "id": {
      "type": "integer",
      "readOnly": true
    },
    "mailing_list_id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "company": {
      "type": "string"
    },
    "address": {
      "type": "string"
    },
    "address2": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "province": {
      "type": "string",
      "description": "State or Province"
    },
    "postal_code": {
      "type": "string"
    },
    "country": {
      "type": "string"
    },
    "dob": {
      "type": "string",
      "description": "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."
    },
    "anniversary": {
      "type": "string",
      "description": "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."
    },
    "email": {
      "type": "string"
    },
    "phone": {
      "type": "string"
    },
    "custom1": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom2": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom3": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom4": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom5": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom6": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom7": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom8": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom9": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "custom10": {
      "type": "string",
      "description": "Custom field for additional information about the recipient"
    },
    "absentee_address": {
      "$ref": "#/$defs/absentee-address"
    },
    "absentee_city": {
      "$ref": "#/$defs/absentee-city"
    },
    "absentee_province": {
      "$ref": "#/$defs/absentee-province"
    },
    "absentee_postal_code": {
      "$ref": "#/$defs/absentee-postal-code"
    },
    "mailing-list": {
      "readOnly": true,
      "allOf": [
        {
          "$ref": "#/$defs/mailing-list"
        }
      ],
      "description": "The mailing list this recipient belongs to"
    },
    "created_at": {
      "readOnly": true,
      "type": "string"
    },
    "updated_at": {
      "readOnly": true,
      "type": "string"
    }
  },
  "$defs": {
    "absentee-address": {
      "type": "string",
      "description": "The property (absentee) address for this recipient, such as a house an absentee owner owns, as opposed to where they get mail. Give either the whole address here, or the street line here with `absentee_city`, `absentee_province` and `absentee_postal_code`. When set, the `~ABSENTEE_STREET~`, `~ABSENTEE_FULL_ADDRESS~`, `~FULL_ADDRESS~` and `~STREET_VIEW~` image template variables, and `%ABSENTEE_STREET%` in messages, use this address instead of the mailing address. The mailer is still delivered to `address`. Include the city, state and ZIP so Street View finds the right property. It is stored and returned in its own `absentee_address` field, and also copied into `custom2` when that is empty, so templates that print `%CUSTOM2%` keep working; a `custom2` you send is never changed. The older convention of `custom1` = `absentee` with `custom2` = the property address is still accepted and copied into `absentee_address`."
    },
    "absentee-city": {
      "type": "string",
      "description": "City of the absentee (property) address. Requires `absentee_address` in the same request."
    },
    "absentee-postal-code": {
      "type": "string",
      "description": "ZIP or postal code of the absentee (property) address. Requires `absentee_address` in the same request."
    },
    "absentee-province": {
      "type": "string",
      "description": "State or province of the absentee (property) address. Requires `absentee_address` in the same request."
    },
    "mailing-list": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "user_id": {
          "type": "integer"
        },
        "sub_account_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "type": {
          "type": "string",
          "enum": [
            "csv",
            "manual",
            "map",
            "friends",
            "retarget",
            "leads",
            "zapier",
            "radius",
            "highlevel",
            "qrscans"
          ]
        },
        "description": {
          "type": "string"
        },
        "qrcode_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "total_recipients": {
          "type": "integer"
        },
        "processed": {
          "type": "boolean"
        },
        "is_suppression_list": {
          "type": "boolean"
        },
        "total_scans": {
          "type": "integer"
        },
        "unique_scans": {
          "type": "integer"
        },
        "last_scan": {
          "type": [
            "string",
            "null"
          ]
        },
        "total_sends": {
          "type": "integer"
        },
        "last_send": {
          "type": [
            "string",
            "null"
          ]
        },
        "api_key": {
          "type": "string",
          "description": "API key that can be used to add recipients to this mailing list with thanks.io Webhooks"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "created_at_diff": {
          "type": "string",
          "description": "Human-friendly relative time since creation"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}