Validate PIN (API)

This document will go over how to validate PIN codes using our RESTFul 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

Request

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

JSON Body

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

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:

{
  "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"
}

Please note: The PIN code is valid for a maximum of 10 attempts. After which the PIN will permanently expire and the process will have to be restarted.

Expired PIN code response

Here is an example of an expired PIN code's response, HTTP Status Code 440:

{
  "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:

{
  "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"
}