# Validate PIN (API)

After calling the **initiate** method via our API and receiving **pending\_pin** state in response, you are supposed to have user presented with a form where they can enter a numeric PIN code (5-6 digits). This is a **POST** request. 

### Example request

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

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

{% 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`.                                                                                                   |

### Invalid PIN code response

Here is an example of an invalid PIN code response, this is your response if the user enters a random or incorrect PIN code, **HTTP Status Code 417**:

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

{% hint style="info" %}
**Please note**: The PIN code is valid for a maximum of **10 attempt**s. After which the PIN will permanently expire and the process will have to be restarted.&#x20;
{% endhint %}

### Expired PIN code response

Here is an example of an expired PIN code's response, **HTTP Status Code 440**:&#x20;

```json
{
  "authenticated" : True,
  "valid_msisdn" : True,
  "valid_campaign" : True,
  "campaign_status" : "active",
  "campaign_name" : "Test Campaign",
  "campaign_service" : "12345",
  "state" : "pending_pin",
  "error" : "Maximum number of failed attempts! PIN is no longer existing!",
  "reference": "AP:aaaaaaa-bbbbbbbbb-cccccccc"
}
```

### Successful response

If the user's PIN code is submitted successfully the following response can be expected, **HTTP Status Code 200**: &#x20;

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