SOAP API Integration - Demographics Method

    Follow

    Purpose of the Demographics Method

    The Demographics integration method handles adding new and updating existing demographic attributes without having to log into the gCast interface to do so. Clients whose demographic attributes change frequently in their external system would find this operation useful.

    The Demographics method operations currently available are (in alphabetical order):

    UpdateDemographicDefinition

    UpdateDemographicDefinitionBatch

    UpdateDemographicDefinitionBatchResult

    UpdateDemographicDefinition
    Purpose
    This operation is useful for clients that administer their demographics and attributes externally but want to synchronise that data into their gCast database, effectively creating demographics and their attributes ‘on the fly’.
    API Requests
    API requests can be passed to gCast containing one or more demographic attributes, consisting of reference, description, answer type, and (in the case of multi-choice demographics) one of either lookup type or one or more answer choices. All other fields must be edited manually in gCast if required.
    API Returns
    The API will return a series of messages in XML code. Each message will contain the message severity, message code, message text, record number, and reference ID:

    • Message severity - ‘Information’, ‘Warning’, or ‘Error’
    • Message code – a list of message codes can be retrieved using the Lookup method
    • Message text – a brief description of the nature of the message
    • Record number – this will correspond to the line number of the record that was passed in via the request
    • Reference ID – this will correspond to a unique identifier relevant to the record that was passed in via the request (e.g. demographic attribute reference, external ID)

    UpdateDemographicDefinitionBatch
    Purpose
    This operation is used for the same purpose as the UpdateDemographicDefinition operation. The difference is that this is a batch process and is useful where you don’t need the results immediately.
    API Requests
    API requests can be passed to gCast containing one or a list of subscriber references, a number of points and notes that will be stored against the points. Points may be positive or negative.
    API Returns
    The API will return a unique ID (32-character GUID) that you can use to retrieve the batch submission at a later point in time (using the UpdateDemographicDefinitionBatchResult operation).

    UpdateDemographicDefinitionBatchResult
    Purpose
    This operation is used for the purpose of retrieving the results of the UpdateDemographicDefinitionBatch operation. You would start calling this operation no sooner than 5 minutes after calling the UpdateDemographicDefinitionBatch operation, and probably call it every few minutes thereafter until you receive a status indicating completion or failure.
    API Requests
    API requests can be passed to gCast containing one or a list of unique IDs (per the UpdateDemographicDefinitionBatch operation).
    API Returns
    The API will return a batch status of ‘Not Found’, ‘Queued’, or ‘Processing’ up until the batch itself is no longer considered to be ‘in progress’, at which point a batch status of ‘Complete’ will be returned along with a series of messages in XML code. Each message will contain the message severity, message code, message text, record number, and reference ID:

    • Message severity - ‘Information’, ‘Warning’, or ‘Error’
    • Message code – a list of message codes can be retrieved using the Lookup method
    • Message text – a brief description of the nature of the message
    • Record number – this will correspond to the line number of the record that was passed in via the request
    • Reference ID – this will correspond to a unique identifier relevant to the record that was passed in via the request (e.g. demographic attribute reference, external ID)
    • Batch status - 'Not Found' (GUID does not exist), 'Queued', 'Processing', 'Complete', 'Bad Credentials' (Bad username/password combination), or 'Unauthorised' (insufficient access permission) 
    Was this article helpful?
    0 out of 0 found this helpful

    Comments