# Initiate Subscription (API)

To initiate a subscription via our RESTFul API you must make the following **POST** request: 

{% tabs %}
{% tab title="Request" %}

```hsts
https://subscription-api.mobivate.com/subscriptions/v1/<campaign_id>/initiate
```

{% endtab %}

{% tab title="JSON Body" %}

```json
{
    "msisdn":"xxxxxxxxxxx"
    "signature":"xxxxxxxxxxxxxxxxxx"
    "keyword":"xxxxxxxx"
    "pin":"1234"
}
```

{% endtab %}
{% endtabs %}

### Parameters

| Parameter | Description                                                                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| msisdn    | The unique **MSISDN** you are trying to unsubscribe.                                                                                             |
| signature | Unique parameter consisting of three values: **campaign\_id**, **msisdn** and **account\_id**. For example:  `1af289e14aa593c843da7cd869a8e2f7`. |
| keyword   | Your unique Mobivate keyword.                                                                                                                    |
| pin       | Your validated PIN code. For example: `12345`.                                                                                                   |

### Successful response

If your initiate subscription was successful, you will receive a HTTP Status Code: 200:

```json
{
  "authenticated" : True,
  "valid_msisdn" : True,
  "valid_campaign" : True,
  "campaign_status" : "active",
  "campaign_name" : "Test Campaign",
  "campaign_service" : "12345",
  "state" : "pending_pin",
  "error" : Null,
  "reference": "AP:aaaaaaa-bbbbbbbbb-cccccccc"
}
```

### Failed response

In case the campaign id is invalid or campaign is no longer available, the following status will be returned, HTTP Status Code: 404:&#x20;

```json
{
  "authenticated" : True,
  "valid_msisdn" : True,
  "valid_campaign" : False,
  "campaign_status" : Null,
  "campaign_name" : Null,
  "campaign_service" : Null,
  "state" : Null,
  "error" : "CampaignID '...' not found!",
  "reference": "AP:aaaaaaa-bbbbbbbbb-cccccccc"
}
```

### Additional parameters/User Information

When submitting the subscription **initiate response,** you can also submit additional information that you have obtained about the subscriber. Here is a list of some of the additional parameters you can submit:&#x20;

| Parameter       | Description                               |
| --------------- | ----------------------------------------- |
| first\_name     | First Name                                |
| last\_name      | Last Name                                 |
| email           | Valid Email Address                       |
| dob             | Date of birth                             |
| ip              | Valid IPv4 Address                        |
| handset         | Device/Make/Model/ID                      |
| custom\_data    | Any custom data in JSON format. Under 1kb |
| traffic\_source | A name/ID to identify this traffic source |