Contents x
    Onboarding File
    • 20 May 2025
    • 7 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Onboarding File

    • Updated on 20 May 2025
    • 7 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    The Onboarding File format is used to onboard Customers or Patients to Relay. During the onboarding process, an optional message can be sent to the Customer or Patient. The message to be sent is identified by the trigger_id field.

    If a Customer or Patient is re-onboarded, then the existing Customer or Patient data will be updated with the new data provided in the onboarding file.

    If a trigger_id is specified and the Customer or Patient has a valid consent, then the Relay experience will be sent regardless if this is a new onboard or if an existing Customer or Patient is being updated.

    If a Client has mobile analysis and strict onboarding enabled, for all phone numbers that are not considered as type “mobile”, the onboarding process will include the record in the reject file, indicating that the specific number is non-mobile and was not included on the Customer or Patient account.

    Data File Properties: Onboarding

    Property

    Data Type

    Length

    Required

    Description

    ccid

    string

    100

    Yes

    The unique identifier of the Customer.

    phone_number

    string

    10

    Yes

    The phone number associated with the Customer or Patient expressed only using numeric values.

    product_group

    string

    100

    Yes

    The current product group identifier of the Customer. An account is associated to one and only one product group at a time.

    consent_type

    string

    100

    Yes

    Specifies the type of consent assigned to Customer's or Patient's phone number.

    Valid values are:

      written    The phone number will have express written consent.

      express   The phone number will have express consent.

    trigger_id

    string

    100

    No

    The unique Trigger identifier that was the originating source of the event.

    deactivate_previous_connections

    boolean

    N/A

    No

    This processing flag is used to control how existing phone numbers, for an existing Customer or Patient, should be treated.

    trueAll existing connections will be removed prior to onboarding the new data.
    falseExisting connections will not be removed prior to onboarding. If onboarding with a new mobile number it will be added to the list of existing connections.

    secondary_account_id

    string

    100

    No

    This field can be used to tie the Customer back to another external system.

    first_name

    string

    100

    No

    The first name of the Customer or Patient.

    middle_name

    string

    100

    No

    The middle name of the Customer or Patient.

    last_name

    string

    100

    No

    The last name of the Customer or Patient.

    address1

    string

    100

    No

    Identifies the first line of the Customer's or Patient's address.

    address2

    string

    100

    No

    Identifies the second line of the Customer's or Patient's address.

    city

    string

    100

    No

    Identifies the city of the Customer's or Patient's address.

    state_province

    string

    2

    No

    Identifies the state or province of the Customer's or Patient's address.

    postal_code

    string

    10

    No

    Identifies the postal code of the Customer's or Patient's address.

    date_of_birth

    date

    No

    Identifies the date of birth of the Customer or Patient.

    Format: yyyy-mm-dd

    ssn_last4

    string

    4

    No

    The last 4 digits of the Customer's or Patient's social security number.

    gender

    string

    1

    No

    Identifies the gender of the Customer or Patient.

    ext_xxx

    string

    100

    No

    Client defined, extensible properties to be stored with the Customer or Patient record. Each extensible property must be defined with a prefix "ext_".

    • Custom ext_ properties are provided by the Client.
    • Zero or more ext_ properties can be provided.
    • Different ext_ properties can be provided for each Customer or Patient.
    • The maximum length of each ext_ property is 100 characters.

    EXT_LANG

    string

    100

    No

    This field can be used to designate whether the users's feed should be in English or Spanish.  The header is case sensitive.  Please work with your Relay Account team to ensure you have Spanish feed settings enabled as well.

    Values

    ES The user's feed should be in Spanish

    EN or Null The user's feed should be in English

    input_xxx

    string

    100

    No

    Input parameters to be used in the experience. Each input parameter is prefixed with "input_" followed by the input parameter name.

    • Custom input parameters are provided by the Client.
    • Zero or more input_ parameters can be specified.
    • Different input_ parameters can be specified on each row in the file.
    • The maximum length of each input_ parameter is 100 characters.

    client_message_tag

    string

    100

    No

    An optional, Client created, tag that was provided during the initial messaging/onboarding request.

    lb_name

    string

    255

    No

    Launched by name. If set, identifies the name of the user that triggered the notification.

    lb_source

    string

    255

    No

    Launched by source. If set, identifies the source system that triggered the notification.

    Sample File

    onboarding-with-input-and-ext
    575 Byte

    Rejection Files

    A rejection report will be posted for each input file provided to Relay.  The report will take on the name of the input file, with "REJECT-" appended to the front of the filename.

    • Files are posted to the SFTP pickup folder/sub-folder matching the file type.  See File Transmissions

    • File formats match the input file format with the addition of an Errors column at the beginning of the file that includes the reason a record was rejected

    Rejection Reasons:

    Error Message

    Description

    Ccid exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    Ccid contains whitespace

    There is whitespace detected in your CCID field and this is not accepted.  The whitespace should be removed in order to process the record.  Hint: If not immediately visible, check to see if there was a whitespace added to the end of the CCID

    Ccid not provided

    There was no value in the CCID field, and this is a required field

    Product group exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    Product group not provided

    There was no value in the PRODUCT_GROUP field, and this is a required field

    Secondary account id exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    First name exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    Middle name exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    Last name exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    Address1 exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    Address2 exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    City exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    State province exceeds allowed length (2)

    The number of characters provided in this field exceeds the limit for the field

    Postal code exceeds allowed length (10)

    The number of characters provided in this field exceeds the limit for the field

    Country exceeds allowed length (2)

    The number of characters provided in this field exceeds the limit for the field

    Client Message Tag exceeds allowed length (100)

    The number of characters provided in this field exceeds the limit for the field

    Country expected as 2 alpha characters

    The number of characters provided in this field exceeds the limit for the field

    Date of birth expected as yyyy-mm-dd

    The value provided in the DATE_OF_BIRTH field was in a different format than expected.  The format should be yyyy-mm-dd.  

    Hint: Re-opening a .csv file can cause the format to revert back to a different format.  If you have to open the file for any reason prior to processing, we recommend updating the format for this field proactively.

    Ssn last4 expected as 4 numerical digits

    The number of characters provided in this field exceeds the limit for the field

    Gender expected as 1 alpha character

    The number of characters provided in this field exceeds the limit for the field

    Phone type exceeds allowed length (8)

    The number of characters provided in this field exceeds the limit for the field

    Phone type expected as mobile or landline or unknown

    The values for this field must be one of three options: mobile, landline or unknown

    Trigger id exceeds allowed length (100)

    The trigger ID is too long.  

    Note: The trigger ID can be found in the message builder within CX Builder

    The journey with journey_id journey_id is archived

    The trigger ID is valid, but the experience was archived in CX Builder

    No journey found for trigger_id trigger_id

    The trigger ID provided is not associated with an experience in CX Builder

    Note: Check that the experience has been created in that environment, case sensitivity, and monitor for any extra spaces in the file or on the trigger ID in CX Builder

    Message must be under 5000 characters in length

    Message is too long

    Message contains disallowed html tag

    The message contains hidden html tags.  Navigate to the experience in CX Builder, re-paste the content into a plain text editor to remove additional html, re-paste into the experience and re-save.

    Duplicate message suppression is active

    Duplicate message suppression is based on unique values of CCID, trigger_id, dynamic parameters, and consent_type. When a second message is attempted within 15 minutes of the first message, and all of those values are the same, the message will be suppressed. The suppression is lifted after 15 minutes.  This logic will also be triggered if you attempt to send more 10 SMS messages to the same customer in a 10-minute window.

    Missing input parameters: param1, param2, …, paramN

    The message being launched has dynamic paramaters, no alternate message is setup, and no dynamic parameters have been provided.  

    Note: Check for case sensitivity, extra spaces, and ensure the naming convention matches

    No notification channels exist for this account

    The phone number provided was a non-mobile number and was not added to the account, therefore there are no phone numbers associated with that CCID to trigger a message

    No-consent

    The consent for that phone number is “stop” in Relay, so the message cannot be sent

    Channel-deactivated

    The phone number was deactivated from that CCID

    Invalid product group: product_group

    The value provided in the product group field does not match any of the values in CX Builder.  Verify the product_group values with your Relay Account Team members.

    internal error

    The request timed out.  Try re-processing the records

    Was this article helpful?
    What's Next
    ESC

    Eddy AI, facilitating knowledge discovery through conversational intelligence