Authentication

STAGING_URL: https://switchapi3.azurewebsites.net
LIVE_URL: https://switchapi.azurewebsites.net

Register User

POST https://switchapi3.azurewebsites.net/user/register

Registers user and returns a valid token used for session validation

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
sales_agent_referral_code	string	Referral code of the sales agent.
referrer	string	Switch ID of the referrer.
bvn	string	The user's bvn. Required for Nigerian users.
country	string	country of user, default is `nigeria`
gender	string	gender of user
date_of_birth	string	date of birth of user, in the format YYYY-MM-DD
phone	number	preferred phone number of user
last_name	string	last name of user
first_name	string	first name of user
password	string	preferred password of user, which must contain at least one upper case letter, one lower case letter, one digit and at least one special character
email	string	email address of user

200

{
  "message": "User created successfully",
  "data": {
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMzk2IiwiY29udGV4dCI6InVzZXIiLCJpYXQiOjE1NzcyODg1MjksImV4cCI6MTU3NzI5MDMyOX0.2AwxVSj2QzYCB5cZySUjJ8nRU3guZHtgQbvl1BcQWyc",
    "user": {
      "is_verified": false,
      "blacklisted": false,
      "two_factor_authentication_enabled": false,
      "two_factor_authentication_type": "none",
      "phone_verified": false,
      "pin_set": false,
      "google_auth_set_up": false,
      "disabled": false,
      "has_pending_disable_request": false,
      "has_pending_enable_request": false,
      "fraud_status": "whitelisted",
      "id": "396",
      "email": "[e-mail]",
      "first_name": "Somebody",
      "last_name": "Anybody",
      "date_of_birth": "1996-10-06",
      "phone": "[phone]",
      "gender": "male",
      "country": "NG",
      "photo_id_url": null,
      "image_selfie_url": null,
      "signature_url": null,
      "address": null,
      "switch_id": 100496,
      "payment_link_slug": null,
      "city": null,
      "state": null,
      "zipcode": null,
      "last_sign_in": null,
      "photo_id_issuer": null,
      "photo_id_number": null,
      "photo_id_expiry": null,
      "switch_bank_account_name": null,
      "switch_bank_account_number": null,
      "nigerian_contact_name": null,
      "nigerian_contact_phone": null,
      "nigerian_contact_address": null,
      "nigerian_contact_relationship": null,
      "switch_bank_customer_id": null,
      "verified_at": null,
      "verification_requested": false,
      "bvn": "22xxxxxx032",
      "security_question_set": false,
      "is_diaspora": false,
      "has_wallet": false
    }
  }
}

400

{
  "message": "Error occurred creating user",
  "errors": {
    "password": "must contain at least one upper case letter, one lower case letter, one digit and at least one special character"
  }
}

Login User

POST https://switchapi3.azurewebsites.net/user/login

Authenticates user and returns a valid token used for session validation.

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
email	string	email of user
password	string	password of user

200 Successful login

{
  "message": "User login successful",
  "data": {
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTEiLCJjb250ZXh0IjoidXNlciIsImlhdCI6MTU3NzI4ODkwMCwiZXhwIjoxNTc3MjkwNzAwfQ.Aqt4XZbsQqc8UqEuh51ytc7IrNMEhXSPFSvdX3BQSpw",
    "user": {
      "id": "11",
      "email": "[e-mail]",
      "phone": "[phone]",
      "first_name": "Beyonce",
      "last_name": "Knowles",
      "date_of_birth": "1981-09-04",
      "photo_id_url": "[phone]_id_card_beyonce.jpg",
      "image_selfie_url": "[phone]_image_selfie_url_beyonce.jpg",
      "signature_url": null,
      "address": "19, Okotie Eboh",
      "is_verified": false,
      "gender": "female",
      "country": "NG",
      "blacklisted": false,
      "switch_id": 100111,
      "two_factor_authentication_enabled": true,
      "two_factor_authentication_type": "pin",
      "phone_verified": true,
      "pin_set": true,
      "payment_link_slug": "100111",
      "city": "Ikoyi",
      "state": "Lagos",
      "zipcode": "101233",
      "last_sign_in": "2019-02-11T13:21:59.409Z",
      "photo_id_issuer": null,
      "photo_id_number": null,
      "photo_id_expiry": null,
      "switch_bank_account_name": null,
      "switch_bank_account_number": null,
      "google_auth_set_up": false,
      "nigerian_contact_name": null,
      "nigerian_contact_phone": null,
      "nigerian_contact_address": null,
      "nigerian_contact_relationship": null,
      "switch_bank_customer_id": null,
      "disabled": false,
      "has_pending_disable_request": false,
      "has_pending_enable_request": false,
      "fraud_status": "whitelisted",
      "verified_at": null,
      "verification_requested": false,
      "bvn": null,
      "security_question_set": true,
      "is_diaspora": false,
      "has_wallet": true
    }
  }
}

401 Unsuccessful login

{
    "message": "Invalid login details"
}

Forgot Password

POST https://switchapi3.azurewebsites.net/user/forgot_password

Creates a reset password token, attaches it to user account and sends a reset link to user's email

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
email	string	email address of user

200 password reset email successfully sent

{
    "message": "If this email exists, a password reset email will be sent to it"
}

Reset Password

POST https://switchapi3.azurewebsites.net/user/reset_password

Resets user password

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
security_question_answer	string	The answer to the security question. Required only if the user has set one or more security questions.
security_question_id	integer	The id of the security question. Required only if the user has set one or more security questions
password_confirmation	object	password confirmation
reset_password_token	string	the token that was sent to the user via email
password	string	the preferred password

200

{
    "message": "Password changed successfully"
}

400

{
    "message": "Password could not be updated",
    "errors": {
        "password": "can't be blank"
    }
}

Unlock Account

POST https://switchapi3.azurewebsites.net/user/unlock_account

Unlocks a locked account

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
unlock_token	string	the unlock token sent to the user via email

200

{
    "message": "Account unlocked successfully"
}

400

{
    "message": "Account could not be unlocked",
    "errors": {
        "unlock_token": "is invalid"
    }
}

Resend Unlock Email

POST https://switchapi3.azurewebsites.net/user/resend_unlock_email

Re-sends the unlock email

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
email	string	user email

200

{
    "message": "If this email exists and there's a lock, unlock instructions will be sent to it"
}

Logout

POST https://switchapi3.azurewebsites.net/user/logout

Invalidates the session token

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID
Authorization	string	token in the format Bearer token_string

200

{
    "message": "User session invalidated"
}

401

{
    "message": "Invalid token"
}

Validate user's BVN details

POST https://switchapi3.azurewebsites.net/user/validate_user_bvn

Validates the user's bvn.

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
date_of_birth	string	The user's date of birth.
last_name	string	The user's last name.
first_name	string	The user's first name.
bvn	string	The user's bvn.

200

{
    "message": "BVN validated successfully"
}

400

{
    "message": "BVN is invalid, please confirm your bvn and try again"
}

Send email confirmation

POST https://switchapi3.azurewebsites.net/user/send_email_confirmation_mail

This endpoint is used to send a confirmation email to a user.

Headers

Name	Type	Description
SWI-CS	string	Payload checksum
SWI-CID	string	Client ID

Request Body

Name	Type	Description
email	string	The user's email

200

{
  "message": "Confirmation email sent"
}

Get Referrer

GET https://switchapi3.azurewebsites.net/user/referrer/:switch_id

This endpoint gets the referrer using the switch_id.

Path Parameters

Name	Type	Description
switch_id	string	The switch_id of the referrer.

Headers

Name	Type	Description
SWI-CID	string	Client ID

200

{
    "message": "Referrer retrieved successfully",
    "data": {
        "first_name": "Dan",
        "last_name": "Sawyerr",
        "switch_id": "100789"
    }
}

400

{
    "message": "Invalid referral link"
}