Export customers

Submit and poll

For the general submit-and-poll flow, see Exports overview.

Request

https://api.maestra.io/v3/operations/sync?endpointId={endpointId}&operation={operation}

Accept: application/json
Content-Type: application/json
Authorization: SecretKey {Secret key}

{
  "sinceDateTimeUtc": "<Start of the change window, inclusive — UTC, YYYY-MM-DD hh:mm>",
  "tillDateTimeUtc": "<End of the change window — UTC, YYYY-MM-DD hh:mm>",
  "segment": {
    "ids": {
      "externalId": "<Customer segment external ID>"
    }
  }
}

You can pass:

sinceDateTimeUtc — only customers whose last change is on or after this UTC datetime will be included.
tillDateTimeUtc — only customers whose last change is before this UTC datetime will be included.
externalId of a customer segment — required if you didn't pick one in the operation step settings.

✅
A customer is included when:
sinceDateTimeUtc ≤ last change datetime < tillDateTimeUtc

Filtering is done only by the last change datetime. Creation counts as a change, so there's no separate filter for creation date.

Response format

{
  "customers": [
    {
      "ids": {
        "mindboxId": "<Maestra ID>",
        "<Identifier system name>": "<Identifier value>"
      },
      "firstName": "<First name>",
      "lastName": "<Last name>",
      "email": "<Email address>",
      "isEmailInvalid": "<The email address is invalid>",
      "mobilePhone": "<Mobile phone number>",
      "isMobilePhoneInvalid": "<The mobile phone is invalid>",
      "area": {
        "ids": {
          "externalId": "<Customer's geographic zone ID>"
        },
        "name": "<Customer's geographic zone name>"
      },
      "birthDate": "<Date of birth (yyyy-MM-dd)>",
      "sex": "<Sex>",
      "changeDateTimeUtc": "<Registration or last edit datetime (yyyy-MM-dd HH:mm:ss.fff)>",
      "TimeZone": "<Time zone>",
      "timeZoneSource": "<Time zone source>"
    }
  ]
}

Contact fields can be excluded from the export, or included in hashed form.
- The hash algorithm is set in the operation settings: MD5 or SHA-256.
- Phone numbers are stripped of everything except digits, with no spaces, and include the country code.
- Emails are lowercased and stripped of spaces before hashing.

Custom fields

{
  "customers": [
    {
      ...
      "customFields": {
        "<Custom field system name>": "<Custom field value>"
      }
    }
  ]
}

The operation settings can restrict the export to specific custom fields.

Subscriptions

{
  "customers": [
    {
      ...

      "subscriptions": [
        {
          "brand": "<Brand>",
          "pointOfContact": "<Touchpoint>",
          "topic": "<Topic>",
          "isSubscribed": "<true/false>"
        }
      ]
    }
  ]
}

The operation settings can restrict the export to subscriptions for a specific brand.

Discount cards

{
  "customers": [
    {
      ...
      "discountCards": [
        {
           "ids": {
             "number": "<Discount card number>"
           },
           "status": "<active/blocked>",
           "type": {
             "ids": {
               "externalId": "<Discount card type ID>"
             },
             "name": "<Discount card type name>"
           },
           "customFields": {
             "<Custom field system name>": "<Custom field value>"
           }
        }
      ]
    }
  ]
}

Discount cards can only be exported in XML or JSON.

Bonus point balances

{
  "customers": [
    {
      ...

      "balances": [
        {
          "balanceType": {
            "ids": {
              "systemName": "<Balance system name>"
            },
            "name": "<Balance name>"
          },
          "total": "<Total balance>",
          "available": "<Available balance>",
          "blocked": "<Blocked balance>"
        }
      ]
    }
  ]
}

Segments the customer belongs to

{
  "customers": [
    {
     ...
      "segmentations": [
        {
          "ids": {
              "externalId": "<Segmentation external ID>"
            },
          "name": "<Segmentation name>",
          "segment": {
              "ids": {
                "externalId": "<Segment external ID>"
              },
              "name": "<Segment name>"
            }
        }
      ]
    }
  ]
}

Updated about 2 months ago