Introduction

The Taguchi V5 API supports key customer management, messaging and logging interactions, including:

• Creating and updating subscriber profiles
• Erasing personally identifiable information (PII) associated with subscribers
• Logging interactions (e.g. purchases, cart abandonments, website visits) against subscriber profiles
• Sending messages including email and SMS to subscribers

All Taguchi V5 API endpoints accept data in JSON format.

Provisioning

V5 API endpoints are provisioned via Settings > Integrations. Administrator access to Taguchi is required to provision new authentication methods, while Integration - Manage access is required to manage the API endpoints themselves.

Endpoints support the following authentication methods:

• Unauthenticated (e.g. for publicly-accessible web forms): supports subscriber profile create or update operations, event logging, and message delivery.
• Token: uses a static API token for authentication. The API token must be created Settings > Credentials area of the UI.
• JSON Web Token (JWT) with pre-shared key: uses symmetric cryptography (HS256) based on a pre-shared key to validate an access token provided by the API client. The pre-shared key must be created in the Settings > Credentials area of the UI.
• JWT with public key: uses asymmetric cryptography (RS256) based on a public/private keypair to validate an access token provided by the API client. The keypair is generated on a client system and the public key must be uploaded to the Settings > Credentials area of the UI.

Once the endpoint credentials have been configured, the endpoint integration must be created using the "V5 API Endpoint (Authenticated)" or "V5 API Endpoint (Unauthenticated)" types.

Authentication

All API requests must be made over HTTPS. The authentication requirements depend on the type of API endpoint created.

The base URL structure should be as follows:

https://{server}.taguchimail.com/apiv5_auth/{environment}/{endpoint-id}/subscriber

The {server} used in requests is typically edm2.taguchimail.com, but can vary if a custom domain has been configured for the server.

The {environment} is either prod for production requests, or test for test requests. Until the API endpoint is activated via the blue "Activate" button, only test requests are permitted. Test requests will be processed in the same way as production requests, but will not modify data or send messages.

The {endpoint-id} is a UUID generated once the integration is saved for the first time. Once saved, the integration's base URL will be shown in the "Endpoint URL" field, and an OpenAPI specification will be made available to download.

If in doubt, contact Taguchi Support.

Token authentication

To authenticate using a static token ("API token" credential type), use HTTP Bearer Authorization by sending the token in the following header in the HTTPS request:

Authorization: Bearer <token>

The token can optionally be transmitted in Base64-encoded form. Authentication failures will be indicated by a 403 error code.

JSON Web Token authentication

To authenticate using a JSON Web Token (JWT), you must either configure a symmetric ("API secret key") or asymmetric ("API public key") cryptography credential.

If using symmetric cryptography, the key you enter in the credential must be the same as you use to generate the JWT signature in your API client, and this key must be kept secret as exposing it will allow others to generate valid signatures. This type of credential must be used with the HS256 JWT signature algorithm.

If using asymmetric cryptography, you will generate an RSA public/private keypair, and store the private key somewhere accessible to your API client. The public key is provided to Taguchi, and is not required to be kept secret as it can only be used to validate signatures, not to create them. This type of credential must be used with the RS256 JWT signature algorithm.

Aside from a valid signature, Taguchi requires that the JWT include a "sub" (subject) field value matching the API integration token. This ensures that signatures generated for one API integration cannot be re-used on another.

Taguchi recommends that JWTs be generated with an "exp" (expiration) field value between 60 seconds and 10 minutes in the future, to limit abuse of leaked tokens. Note that Taguchi applies a 60 second grace period to expiration timestamps to account for clock skew and proxy delays.

For more information about JWTs, refer here.

Once generated and signed, the JWT must be included in the Authoriation header in the HTTPS request:

Authorization: Bearer <token>

Error Handling

Taguchi uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was missed), and codes in the 5xx range indicate an error with Taguchi's servers (these are rare).

Profile uniqueness

Taguchi supports different types of uniqueness and identity constraint on subscriber profiles. It is important to ensure the uniqueness constraints being used by your API endpoints align with other data sources such as batch file loads or UI uploads.

The following fields are supported as unique identifiers:

• Taguchi ID: this field is generated by Taguchi and always uniquely identifies a subscriber profile;
• External ID (known as ref in code): this is a string value which can contain a UUID or other form of identifier generated by systems under your control;
• Email + phone: this compares both the customer's lowercase email address and the value of the phone field;
• Email: this field contains the customer email address, converted to lowercase for the purpose of assessing uniqueness;
• Phone: this field contains the customer's phone number.

When an API endpoint has been configured to use one of the above identifiers, all requests to that endpoint must use identifiers that match this configuration. In the case of an action that does not retrieve data and will not create a subscriber profile (for example, a Message Send action), Taguchi will also accept the SHA256 hash of the email address or the phone number in place of the actual email address or phone number.

Schemas

The V5 API uses the following common schemas for data:

Target

Target objects are used within actions that need to identify a subscriber profile by Taguchi ID, external ID, email or phone number. If a target object contains id or ref, they must be used alone; otherwise, the target object may contain email and/or phone depending on the API endpoint configuration.

• id (64-bit integer)

  Identifies a subscriber profile by numeric Taguchi ID.

• ref (UTF-8 string)

  Identifies a subscriber profile by external ID.

• email (UTF-8 string)

  Identifies a subscriber profile by lowercase email address.

• phone (UTF-8 string)

  Identifies a subscriber profile by phone number.

Status

Status objects are returned in responses, with one status per action in the request.

• code (32-bit integer)

  Provides a numeric HTTP status code indicating the result of a specific request.

• name (UTF-8 string)

  The name of the status code.

• description (UTF-8 string)

  A longer description of the status, e.g. reason for error.

Message Send

The Message Send object contains details of a message to be sent. Any fields not present in a request take their default value (typically null).

• target (object; required)

  Contains a Target object identifying the subscriber profile the message should be sent to.

• isTest (Boolean)

  If true, the message is sent in test mode: the latest revision content will be used, and statistics will not be gathered.

• requestContent (object)

  If present, may contain a JSON object which will be passed to the activity template, permitting detailed personalization or customization of message contents.

• sendTimestamp (UTF-8 string)

  If present, must be an ISO 8601 UTC datetime; the message will be sent at this date and time. If not present, or if this time is in the past, the message will be sent immediately.

• activityId (64-bit integer)

  The Taguchi ID of the activity to send, if permitted by API endpoint configuration.

Event Log

The Event Log object contains details from the subscriber event log, with fields differing slightly depending on whether the object appears in an event log action within a request, or within an event log record sent from Taguchi to a client webhook endpoint. Any fields not present in a request take their default value (typically null).

• target (object; required)

  Contains a Target object identifying the subscriber profile the event relates to.

• isTest (Boolean)

  If true, the event is a test event, and will not be included in statistics.

• data (object)

  If present, may contain a JSON object which represents custom data associated with the event, for example product details in the case of a purchase.

• type (UTF-8 string; required)

  The type of event (refer to the event list for supported types).

• loggedTimestamp (UTF-8 string)

  If present, must be an ISO 8601 UTC datetime representing the time at which the event occurred.

• activityId (64-bit integer)

  The ID of the activity the event relates to

• id (64-bit integer)

  The Taguchi numeric ID for this event. Ignored if included in an event log action.

List Subscription

The List Subscription object contains details relating to a subscriber's membership of a list. Any fields not present in a request are left unchanged.

• listId (64-bit integer; required)

  The Taguchi ID of the list this subscription relates to.

• importId (64-bit integer)

  If non-null, the Taguchi ID of the import through which the list subscription was created.

• campaignId (64-bit integer)

  If non-null, the Taguchi ID of the campaign through which the list subscription was created.

• subscribedTimestamp (UTF-8 string)

  If present, the ISO 8601 UTC datetime representing the time at which the list subscription was created.

• unsubscribedTimestamp (UTF-8 string)

  If present, the ISO 8601 UTC datetime representing the time at which the subscriber unsubscribed from the list.

• subscriptionOption (UTF-8 string)

  A customer-defined text or serialized JSON field.

Subscriber

The Subscriber object contains a subscriber profile. All fields except for the configured identifying field(s) are optional; if a field is not present in the request, it will be set to the default value during subscriber profile creation, or left unchanged during subscriber profile updates.

• id (64-bit integer)

  The Taguchi ID of this profile.

• ref (UTF-8 string)

  The external ID of this profile, if set.

• email (UTF-8 string)

  The email address of this subscriber profile. Case-insensitive but case-preserving.

• phone (UTF-8 string)

  The phone number of this subscriber profile.

• title (UTF-8 string)

  The subscriber's title.

• firstname (UTF-8 string)

  The subscriber's first name.

• lastname (UTF-8 string)

  The subscriber's last name.

• notifications (UTF-8 string)

  A customer-defined text or serialized JSON field.

• extra (UTF-8 string)

  A customer-defined text or serialized JSON field.

• dob (UTF-8 string)

  If non-null, must be an ISO 8601 date (YYYY-MM-DD) representing the subscriber's date of birth.

• address (UTF-8 string)

  The first line of the subscriber's address.

• address2 (UTF-8 string)

  The second line of the customer's address.

• address3 (UTF-8 string)

  The third line of the customer's address.

• suburb (UTF-8 string)

  The suburb, town or city of the customer's address.

• state (UTF-8 string)

  The state or province of the customer's address.

• country (UTF-8 string)

  The country of the customer's address.

• postcode (UTF-8 string)

  The postcode or ZIP code of the customer's address.

• gender (UTF-8 string)

  The customer's gender.

• unsubscribedTimestamp (UTF-8 string)

  If the customer is globally unsubscribed, must be the ISO 8601 datetime at which they unsubscribed.

• invalidTimestamp (UTF-8 string)

  If the customer's email address is invalid, must be the ISO 8601 datetime at which it was flagged as invalid.

• resumeDate (UTF-8 string)

  If non-null, must be an ISO 8601 date (YYYY-MM-DD) representing the date at which message delivery to this subscriber should resume. Until this date, the subscriber will be treated as unsubscribed.

• organizationId (64-bit integer)

  The Taguchi ID of the organization to which this subscriber belongs.

• campaignId (64-bit integer)

  If non-null, the Taguchi ID of the campaign through which the subscriber was added to the database.

• importId (64-bit integer)

  If non-null, the Taguchi ID of the import through which the subscriber was added to the database.

• custom (object)

  A mapping of customer-defined field names (strings) to field values (strings) for this subscriber profile. When updating an existing profile, only fields present in this object will be modified; a profile's other custom fields will remain unchanged. Field values may be serialized JSON objects.

• lists (object)

  An array of list subscription objects for this subscriber profile. When updating an existing profile, only list subscriptions present in this object will be modified; a profile's other list subscriptions will remain unchanged.

Event types

• v

  Viewed: The subscriber viewed a web page or app screen.

• o

  Opened: The subscriber opened an email or other activity.

• p

  Purchased: The subscriber made a purchase (or triggered another type of conversion).

• wa

  Analytics: The subscriber triggered a custom analytics event, e.g. a web page or app interaction.

• ab

  Abandoned: The subscriber abandoned their cart, or abandoned another conversion process.

• sb

  Submitted form: The subscriber submitted a form via a web page or app.

GET requests

A GET request returns subscriber profiles matching the supplied identifying fields (depending on API endpoint configuration). This request type is only supported for authenticated endpoints as subscriber personally identifiable information is returned.

The request may contain the below fields in the URL query string. If the query contains id or ref, they must be used alone; otherwise, the query may contain email and/or phone depending on the API endpoint configuration.

• id (64-bit integer)

  Identifies a subscriber profile by numeric Taguchi ID.

• ref (UTF-8 string)

  Identifies a subscriber profile by external ID.

• email (UTF-8 string)

  Identifies a subscriber profile by lowercase email address.

• phone (UTF-8 string)

  Identifies a subscriber profile by phone number.

The root-level response object is always an array; if a subscriber profile matching the supplied identification fields is found, the root-level array will contain the matching Subscriber profile object.

If no profile is found, the response will be a 404 error.

POST requests

A POST request submits a series of subscriber profile actions as a JSON array; these actions can include the following:

• Profile create/update (Subscriber profile object)
• Event log (Event Log object)
• Message send (Message Send object)

The root-level object in a request is always an array; actions will be processed in the order they appear in within this array. The array elements for these actions are:

Subscriber profile action:

{"profile": {…}}

Event log action:

{"event": {…}}

Message send action:

{"message": {…}}

Within the above data structures, replace {…} with the relevant object type.

The root-level response object is always an array; the status of each action within the request will be returned within the corresponding element in the response array. Requests succeed or fail independently of each other, although note that e.g. if a subscriber profile action fails to create a subscriber, any subsequent event log or message send actions relating to that subscriber may fail due to the profile not being present.

Up to 100 actions in any combination may be included in each request.

DELETE requests

A DELETE request submits one or more subscriber profiles to be anonymized. The root-level response object is always an array; the status of each action within the request will be returned within the corresponding element in the response array. Requests succeed or fail independently of each other.

The request may contain the below fields in the URL query string. If the query contains id or ref, they must be used alone; otherwise, the query may contain email and/or phone depending on the API endpoint configuration.

• id (64-bit integer)

  Identifies a subscriber profile by numeric Taguchi ID.

• ref (UTF-8 string)

  Identifies a subscriber profile by external ID.

• email (UTF-8 string)

  Identifies a subscriber profile by lowercase email address.

• phone (UTF-8 string)

  Identifies a subscriber profile by phone number.