User-Defined Fields with the API

UDFs may be set / fetched on API resources / entities via our v2 REST API. All applicable resources support the user_defined_fields attribute.

  • Customer
    • POST /services/v2/customer
    • GET /services/v2/customers
    • GET/POST /services/v2/customers/{id}
  • Customer Address
    • GET /services/v2/addresses
    • GET/POST /services/v2/addresses/{id}
  • (Item) Subscription
    • POST /services/v2/subscription
    • GET/PATCH/POST /services/v2/subscriptions
    • GET/PATCH/POST /services/v2/subscriptions/{id}
  • Group Subscription
    • POST /services/v2/group-subscription
    • GET/PATCH/POST /services/v2/group-subscriptions
    • GET/PATCH/POST /services/v2/group-subscriptions/{id}
  • Product
    • GET/PATCH/POST /services/v2/products
    • GET/PATCH/POST /services/v2/products/{id}
  • Group Subscription Template
    • POST /services/v2/group-subscription-template
    • GET/PATCH/POST /services/v2/group-subscription-templates
    • GET/PATCH/POST /services/v2/group-subscription-templates/{id}

UDF support in our v3 REST API endpoints is currently only partially available and will vary based on the individual endpoint.


For example, let's say you wanted to update the birthday user-defined field on a customer's address. You could make an API call like this

Example PATCH Request

curl -X PATCH "" \
  -H 'Authorization: Bearer XXXXXX' \
  --data-binary @- << EOF
    "op": "add",
    "path": "/user_defined_fields/birthday",
    "value": "1985-01-01"

Example GET Request

Then, you could get the customer's address data including that UDF value with an API request like this:

curl -X GET "" \
  -H 'Authorization: Bearer XXXXXX'

Example POST Request

You could also replace all of the UDFs set on a customer address record by doing the following:

curl -X POST "" \
  -H 'Authorization: Bearer XXXXXX'
  --data-binary @- << EOF
  "address": {
    "user_defined_fields": {
      "birthday": "1985-01-01"

Validation of User-Defined Fields

When User-Defined Fields are set or updated via the API, we only validate that the UDF data is valid JSON. When UDF fields with the "Validate Data" setting are edited through the SubscribePro application, we will enforce the validation rules for that field.