Create Subscriber

The CreateSubscriber API in OCS.io allows developers to establish new subscriber records, configuring each with specific attributes to align with operational requirements.

API Overview

Required Fields for Subscriber Creation

The following table lists and describes the fields required to create a subscriber through the CreateSubscriber API:

Field Description

subscriberProfile

Profile of the Subscriber to be used for creation. Subscriber Profile must be configured.

externalId

External ID of the Subscriber.

account

ID (Ref ID / External ID) of the Account.

primaryResourceType

Type of the Primary Resource to be used for the Subscriber. Resource Type must be configured.

primaryResource

Value of the Primary Resource associated with the Subscriber.

subscriberSegment

Segment of the Subscriber. Subscriber Segment must be configured.

customName

Custom name assigned to the Subscriber.

customAttributes

Custom attributes, Key - Value (String) Map.

state

Initial State of the Subscriber.
Detailed API documentation can be found here.

Request Validations

The following validations are performed when creating a subscriber:

  • If Subscriber Profile is provided in the request, it must be configured in the system.

  • If Subscriber Segment is provided in the request, it must be configured in the system.

  • State Reason must be configured in the system for given State.

  • If Pending State is provided in the request, it will be ignored and Subscriber will be created without Pending.

  • If Subscriber Profile is not provided in the request, attributes State and State Reason must be provided in the request.

  • If Account is provided in the request, it must be already created in the system and must not be in Deactivated State.

  • If Account is not provided in the request, Subscriber Profile must be provided in the request.

  • If External ID is provided in the request, it must be unique and must not be already assigned to another Subscriber even in Deactivated State.

  • If Primary Resource is provided in the request, it must be unique and must not be already assigned to another Subscriber in other state then Deactivated.

  • If Primary Resource is provided in the request, Primary Resource Type must be also provided in the request and it must be configured in the system.

Create Subscriber Examples

1. Create Subscriber by Profile

Creating a subscriber in OCS.io is most straightforward when using a pre-configured subscriber profile. For more details on setting up subscriber profiles, see the configuration guide here.

Use the following request’s body to create a Subscriber by Profile:

{
  "requestId": "{{$guid}}",
  "externalId": "subscriber_external_id",
  "subscriberProfile": "internetOnly"
}

The outcome of the API call is as follows:

  • A new subscriber with the external ID subscriber_external_id is created using the configured internetOnly profile.

2. Create Subscriber by Profile with Additional Attributes

To enhance a basic subscriber profile with additional attributes, such as a Custom Name, you can modify the initial request as shown below:

{
  "requestId": "{{$guid}}",
  "externalId": "subscriber_external_id",
  "subscriberProfile": "internetOnly",
  "customAttributes": {
    "key1": "Value 1",
    "key2": "Value 2"
  },
  "customName": "Demo Subscriber"
}

The outcome of the API call is as follows:

  • A new subscriber with the external ID subscriber_external_id is created using the configured internetOnly profile.

  • The custom attributes key1: Value 1 and key2: Value 2 are set for the subscriber.

  • The custom name of the subscriber is set to Demo Subscriber.

3. Create Subscriber by Providing Mandatory Attributes

The last option is to create a subscriber by providing all mandatory attributes:

Use the following request’s body to create a Subscriber by providing all attributes:

{
  "requestId": "{{$guid}}",
  "account": {
    "externalId": "account_external_id"
  },
  "externalId": "subscriber_external_id",
  "subscriberSegment": "topUploader",
  "customAttributes": {
    "key1": "Value 1",
    "key2": "Value 2"
  },
  "state": {
    "state": "ACTIVE",
    "stateReason": "dfltActive"
  },
  "customName": "Demo Subscriber"
}

The outcome of the API call is as follows:

  • A new subscriber, with the external ID subscriber_external_id is created under the account identified by external ID account_external_id.

  • Configured Segment topUploader is assigned to the subscriber.

  • Custom Attributes key1: Value 1 and key2: Value 2 are set to the subscriber.

  • Custom Name Demo Subscriber is set as the subscriber’s name.

  • The subscriber’s state is set to ACTIVE with the reason dfltActive.