Client onboarding

Client resource

The client is the most important resource in Nexta platform. All other resources are somehow related to the client. There are two types of clients:

• Agency
• End-client

Currently, Nexta API does not support creating new agencies. This can be only done in contact with sales & support teams.

Authorized users of the agencies can create end-clients. To create a client it is required to be authenticated as an agency admin user.

The process of creating an end-client is illustrated below.

1. Check health
2. GET available campaign templates for the agency (optional)
3. POST a client
4. Poll until complete

1. Check health

The client onboarding process is started as any other process by checking the health using the health endpoint (GET /api/v3.0/health).

Response	Meaning	Description	Next actions
200	Healthy	All Nexta services are healthy.	Continue the process execution.
500	Unhealthy	1 or more services are unhealthy.	Do not continue. Wait until healthy.

2. GET available campaign templates (optional)

There are 2 ways of getting available campaign templates for a given agency ID.

1. GET client: /api/v3.0/client/{id}
2. GET templates: /api/v3.0/template/{clientId}

Template

Template is a resource that defines which systems and types of the campaigns client can use.

It is also a link to the existing template in external system.

Read template

To get templates available on the client call GET /api/v3.0/template/{clientId} endpoint.

This endpoint returns an array of TemplateDTO objects.

TemplateDTO

Field	Type	Description
ID	int	ID of the template
ClientID	string	ID of the client
Name	string	Name of the template
Description	string	Description
CampaignID	numeric string (long)	Id in the external system
CampaignType	CampaignType enum	Type of the campaign template
DateCreated	DateTime	Date created time
CreatedBy	string	User who created the client
DateUpdated	DateTime	Last updated time
UpdatedBy	string	User who did last update

3. POST a client

You need to do a POST request to this endpoint: /api/v3.0/client

There are two ways of client onboarding.

1. Default - provide only requried data
2. Custom - provide selected templates

Default onboarding

Default onboarding will create a client with all templates available on the agency.

To make a default onboarding please make a call to /api/v3.0/client with the following payload.

{
    "ClientID": "DEFAULT",
    "Name": "Nexta Default"
}

Assuming we are authenticated as a MediaGroup-UK agency the request above should generate a client with the following client ID: MediaGroup-UK_DEFAULT.

Custom onboarding

To perform custom onboarding and use only selected templates on the client the API client needs to get a list of available templates for the given agency as in step 2.

The example of the request payload to /api/v3.0/client endpoint.

{
    "ClientID": "CUSTOM",
    "Name": "Nexta Custom",
    "PublicID": "33357818",
    "Addresses": [{
        "HouseNumberFrom": "58",
        "MunicipalityName": "KØBENHAVN",
        "CountryCode": "DK",
        "PostalDistrict": "Hellerup",
        "ZipCode": "2900",
        "StreetName": "Ryvangs Allé"
    }],
    "Templates": [{
        "ID": 88,
        "ClientID": "MediaGroup-UK",
        "Name": "Display",
        "Description": "Template for display advertising",
        "CampaignID": "1126474",
        "CampaignType": 1,
        "DateCreated": "2017-09-26T14:56:00Z",
        "CreatedBy": "jur",
        "DateUpdated": null,
        "UpdatedBy": "2017-10-17T15:11:00"
    }, {
        "ID": 1411,
        "ClientID": "MediaGroup-UK",
        "Name": "Facebook",
        "Description": "Facebook for MediaGroup-UK",
        "CampaignID": "23842600088750789",
        "CampaignType": 3,
        "DateCreated": "2017-09-26T15:00:00Z",
        "CreatedBy": "jur",
        "DateUpdated": null,
        "UpdatedBy": null
    }]
}

Assuming we are authenticated as a MediaGroup-UK agency the request above should generate a client with the following client ID: MediaGroup-UK_CUSTOM.

4. Poll until complete

The onboarding process takes on average around 2 minutes.

After POST-ing the client, you need to keep querying (GET) the client status /api/v3.0/client/{id}/status endpoint.

Polling approach:

1. GET /api/v3.0/client/{id}/status
2. If the response status is 200 then check the Status field in the response. If Status is "Processing", then wait for 20 seconds and go to 1. If Status is "Active", then the client has been successfully onboarded.
3. If the response status is 404, then the process failed.

Handling process failures

If the client status endpoint returns 404, then something went wrong during the client creation in the 3rd party systems (according to the templates chosen). You should not retry, because this is likely due to a configuration issue that needs to be fixed manually. Nexta will rerun the onboarding within 2 business days. You need to keep retrying once every 15 minutes for 2 business days between 09:00 and 17:00 CET.

In case if the client needs to be promptly onboarded, please contact Nexta support at support@nexta.io.