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
FieldTypeDescription
IDintID of the template
ClientIDstringID of the client
NamestringName of the template
DescriptionstringDescription
CampaignIDnumeric string (long)Id in the external system
CampaignTypeCampaignType enumType of the campaign template
DateCreatedDateTimeDate created time
CreatedBystringUser who created the client
DateUpdatedDateTimeLast updated time
UpdatedBystringUser 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.

{
    "ID": "MediaGroup-UK_DEFAULT",
    "Name": "Nexta Default",
    "PublicID": null,
    "IsAgent": false,
    "DateCreated": "2024-12-12T13:52:50Z",
    "CreatedBy": null,
    "DateUpdated": null,
    "UpdatedBy": null,
    "Status": "Processing",
    "IndustryType": null,
    "PaymentAccountId": "00000000-0000-0000-0000-000000000000",
    "Contracts": null,
    "Templates": null,
    "SystemAccounts": null,
    "Addresses": null,
    "EmailTemplateConfigurations": null
}

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.

5. 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.


Client onboarding flow diagram

Failure response examples

Request validation failure

In case of an invalid request, the HTTP response code is 400.

{
    "errors": {
        "Name": [
            "The Name field is required.",
            "Client name is required."
        ],
            "ClientID": [
            "Maximum length for Client ID is 30"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-e57428d3805e414d081cf31fb6c67a3c-540cf2843126ce88-00"
}

Internal server error

In case of a server erropr, the HTTP response code is 500.

{
    "Service": "NextAdvertising.Gateway.Api",
    "Code": "Unknown",
    "HttpStatusCode": 500,
    "Message": "Value cannot be null. (Parameter 'input')",
    "TraceId": "e8102d3804358363c30979331d4c5e05"
}

Unauthorized

In case of an unauthorized request, the HTTP response code is 401. No payload is returned.

← Error handlingCampaign creation →