To configure this feature, ensure Configuring Campaign Manager is complete.

Users can manage API tokens to control external application access to a journey.

To generate an API token:

1. Navigate to the Add Targets section of the appropriate journey.

2. Select the API tab.

   

3. Select the appropriate expiration date from the Expires drop-down list. The following values are available:

   • 30 Days
   • 90 Days
   • 6 Months
   • 1 Year
   • Journey End – The end date of the journey, if defined. If the journey end date is defined, the list of available values contextually updates. For example, if the journey end date is scheduled for five months in the future, only 30 Days, 90 Days, and Journey End display as available for selection.

   The maximum time a token can be valid is 1 Year. Users can also expire tokens manually once generated.

4. Select Generate Token.

   

5. Copy both the Endpoint and API Token to a separate, secure location for sharing and distribution. The token can only be copied immediately after generating, once it is copied or the user navigates away from this page, the token is obscured and cannot be copied.

Identifying Targets added via API

Marketing users can identify which journey’s targets were added via API using the following columns in the Target List sub-tab:

• Added via – Populates with API for targets added via API
• Source System – The identifier used by the system that submitted the target via API

Users can add targets to journeys using target_loader__v records, either created directly in Vault CRM or upserted via the Vault Loader. When creating target_loader__v records, ensure the following fields are populated:

• submitted_campaign__v – References the appropriate journey ID
• At least one of the following combination of account identifier fields:
• submitted_account_id__v — The ID of the submitted account
• submitted_email__v – The email address of the account
• Both of the following fields:

• submitted_external_id_field__v – Enables defining a specific external ID field on the account__v object to use for matching

  External ID fields must be a Text field. Long Text, Rich Text, or any other subtype of Text field is not supported.

• submitted_external_id_value__v – Specifies the value to match against the defined external ID field

When the record is created, the processing_status__v field updates as the system matches the referenced account.

Matches are made based on the following priority order for each target:

• Vault Account ID – Matches the submitted_account_id__v field on the target_loader__v record against the id field on the account__v object
• External ID – The exact match of the target_loader__v record’s submitted_external_id_value__v field against the field named in the record’s submitted_external_id_field__v on the corresponding field on the account__v object. If the specified field is the id field on the account__v object, then this matching is also case-sensitive.
• Primary email – Matches the submitted_email__v field on the target_loader__v record against the primary_email_cda__v field on the account__v object

Only the highest-priority identifier present is used. Lower-priority identifiers are not used as fallback, even when the highest-priority identifier produces no match.

If a failure occurs, the failure_reason__v field populates to describe why the processing failed. Available values are:

• campaign_ended__v – Indicates the associated campaign has ended
• campaign_not_found__v – Indicates the associated campaign count not be found
• duplicate_submission__v – Indicates that the submission matched to a duplicate of another submission
• field_length_exceeded__v – Indicates that a submitted field exceeded the maximum length of the corresponding field in Vault CRM
• invalid_external_id_field__v – Indicates the submitted external ID was invalid
• multiple_matches__v – Indicates multiple matches were found, meaning the target could not be reconciled to a single account
• no_match_found__v – Indicates no match was found
• required_field_missing__v – Indicates that a required field was excluded from the submission
• service_unavailable__v – Indicates a service error during the API process
• other__v – A reason other than the above listed reasons

If a successful match is found when the target_loader__v record is created, the corresponding target is automatically added to the associated journey.

Business admin users need to understand how the API call is structured and how Target Loader records are logged.

Structuring the API Call

External systems can add targets to a campaign or journey using the appropriate endpoint and API token provided by the marketing user. The API call must have the following structure:

• Method – POST
• Path – The endpoint provided by the marketing user
• Payload – Use a JSON array of up to 500 targets. Each target object in the array must have the following fields populated:
• source_system_id – The identifier of the submitting external system

• At least one of the following combination of account identifier fields:

  Combination	Account Identifier Fields
  A	account_id – The ID of the account in Vault CRM email – The email address of the account
  B	submitted_external_id_field – Enables defining a specific external ID field on the account__v object to use for matching External ID fields must be a Text field. Long Text, Rich Text, or any other subtype of Text field is not supported. submitted_external_id_value – Specifies the value to match against the defined external ID field

Example JSON Format

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
  { 
    "source_system_id": "SRC-001", 
    "account_id": "V4T000000007857", 
    "email": "jane@example.com",
    "submitted_external_id_field": "custom_id__c",
    "submitted_external_id_value": "ACC-012345",
    "first_name": "Jane", 
    "last_name": "Doe" 
  },
  { 
    "source_system_id": "SRC-002", 
    "email": "john@example.com" 
  }
]

The API call can also include the first_name and last_name fields, but these fields are not used for matching within Vault CRM.

Managing Target Loader Records

When targets are added to a journey via an API endpoint, the action is automatically logged by a created target_loader__v record with the following properties:

• journey__v – References the appropriate journey
• source_system_id__v — The identifier used by the system that submitted the target via API
• submitted_email__v — Email address submitted in the API payload
• submitted_account_id__v — The ID of the submitted account
• submitted_first_name__v — The first name from the API call. This field is not used for matching.
• submitted_last_name__v — The last name from the API call. This field is not used for matching.
• submitted_external_id_field__v – The API name of the account__v field submitted for external ID matching
• submitted_external_id_value__v – The external ID value to match against the field named in submitted_external_id_field__v
• account__v — References the matched account
• matching_outcome__v — Lists the outcome of the attempt to match the account from the API call with an account within Vault CRM
• processing_status__v — The current processing status of the record
• failure_reason__v — Only populates if the processing_status__v field is failed__v. Describes why processing failed. The following values are available:
• campaign_ended__v – Indicates the associated campaign has ended
• campaign_not_found__v – Indicates the associated campaign count not be found
• duplicate_submission__v – Indicates that the submission matched to a duplicate of another submission
• field_length_exceeded__v – Indicates that a submitted field exceeded the maximum length of the corresponding field in Vault CRM
• invalid_external_id_field__v – Indicates the submitted external ID was invalid
• multiple_matches__v – Indicates multiple matches were found, meaning the target could not be reconciled to a single account
• no_match_found__v – Indicates no match was found
• required_field_missing__v – Indicates that a required field was excluded from the submission
• service_unavailable__v – Indicates a service error during the API process
• other__v – A reason other than the above listed reasons
• request_uuid__v — System generated unique identifier for each API request

If a successful match is found when the target_loader__v record is created, the corresponding target is automatically added to the associated journey.