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

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

Parameters

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

Last updated