Applications

As the name suggests, contacts are a core part of Protocol — the very reason Protocol exists is so you can have secure conversations with your contacts. On this page, we'll dive into the different contact endpoints you can use to manage contacts programmatically. We'll look at how to query, create, update, and delete contacts.

Endpoints

POST
/applications

Create an application

Request Body

Application object that needs to be added

Schema: Application entity

Request

POST

/applications

{
  "store_id": "store_id",
  "reference_id": "reference_id",
  "promo_code": "promo_code",
  "threatmetrix_session_id": "threatmetrix_session_id",
  "applicant": {
    "location": {
      "city": "city",
      "code": "code",
      "county": "county",
      "country": "country",
      "longitude": "longitude",
      "line_1": "line_1",
      "line_2": "line_2",
      "latitude": "latitude",
      "state": "state"
    },
    "title": "title",
    "first_name": "first_name",
    "middle_name": "middle_name",
    "last_name": "last_name",
    "social_security_number": "social_security_number",
    "date_of_birth": "date_of_birth",
    "email": "e-mail",
    "identification": "id_number",
    "identification_issuer": "id_issuer",
    "phone": "phone_number",
    "cell": "cell_number",
    "primaryIncome": {
      "source": "source",
      "employer": "employer",
      "gross": 123,
      "pay_date": "pay_date",
      "phone": "phone",
      "ext": "ext",
      "frequency": "frequency",
      "first_pay_day": 123,
      "second_pay_day": 123,
      "title_department": "title_department"
    },
    "secondaryIncome": {}
  },
  "banking": {
    "opened_at": "date_account_opened",
    "routing_number": "routing_number",
    "checking_account": "account_number",
    "bank_name": "bank_name",
    "online": true
  },
  "co_applicant": {
    "title": "title",
    "first_name": "first_name",
    "middle_name": "middle_name",
    "last_name": "last_name",
    "social_security_number": "social_security_number",
    "date_of_birth": "date_of_birth",
    "email": "e-mail",
    "identification": "id_number",
    "identification_issuer": "id_issuer",
    "phone": "phone_number",
    "cell": "cell_number",
    "primaryIncome": {},
    "secondaryIncome": {}
  },
  "technician": {}
}

Response

{
  "status": true,
  "code": 200,
  "data": {
    "code": "A",
    "reason": "approved",
    "description": "Approved",
    "determination": "approved",
    "determinationMessage": "Customer has been approved",
    "message": {
      "name": "Test Guy",
      "title": "Congratulations!",
      "options": [
        [
          "Option C",
          "$5,000.00",
          "No initial payment due at signing"
        ]
      ],
      "sub_title1": "You are approved for: "
    },
    "offerAmounts": {
      "C": "5,000.00"
    },
    "optionsApproved": "C",
    "checkoutId": null,
    "application_id": 261382,
    "score": 989,
    "coapplicant_score": null
  }
}

POST
/applications/{application}/add-co-applicant

Adds a co-applicant

Request Body

Application object that needs to be added

Schema: Co-Applicant Entity

Request

POST

/applications/{application}/add-co-applicant

{
  "title": "title",
  "first_name": "first_name",
  "middle_name": "middle_name",
  "last_name": "last_name",
  "social_security_number": "social_security_number",
  "date_of_birth": "date_of_birth",
  "email": "e-mail",
  "identification": "id_number",
  "identification_issuer": "id_issuer",
  "phone": "phone_number",
  "cell": "cell_number",
  "primaryIncome": {
    "source": "source",
    "employer": "employer",
    "gross": 123,
    "pay_date": "pay_date",
    "phone": "phone",
    "ext": "ext",
    "frequency": "frequency",
    "first_pay_day": 123,
    "second_pay_day": 123,
    "title_department": "title_department"
  },
  "secondaryIncome": {}
}

Response

{
  "co_applicant": {
    "title": "mr",
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "social_security_number": "string",
    "date_of_birth": "string",
    "email": "string",
    "identification": "string",
    "identification_issuer": "string",
    "phone": "string",
    "cell": "string",
    "primaryIncome": {
      "source": "employment",
      "employer": "string",
      "gross": 0,
      "pay_date": "string",
      "phone": "string",
      "ext": "string",
      "frequency": "weekly",
      "first_pay_day": 15,
      "second_pay_day": 28,
      "title_department": "string"
    },
    "secondaryIncome": {
      "source": "employment",
      "employer": "string",
      "gross": 0,
      "pay_date": "string",
      "phone": "string",
      "ext": "string",
      "frequency": "weekly",
      "first_pay_day": 15,
      "second_pay_day": 28,
      "title_department": "string"
    }
  }
}

GET
/applications/groups

Get a group of applications

Returns a group of applications

Parameters

Name
purchase_group
Type
string
Description
Purchase Group
Name
page
Type
number
Description
The page number you want returned
Name
stores
Type
array
Description
The stores you want to filter by
Name
statuses
Type
array
Description
The statuses of the applications you want to filter by
Name
sort_by
Type
string
Description
The field you want to sort by
Name
sort_order
Type
string
Description
The direction you want to sort by
Name
date_from
Type
string
Description
The starting date.
Name
date_to
Type
string
Description
The finishing date.
Name
date_type
Type
string
Description
The date type you want to use.

Request

GET

/applications/groups

Response

{
  "status": true,
  "code": 200,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 259867,
        "state_code": "V",
        "store_id": 12621,
        "created_at": "2022-02-04T14:59:45.000000Z",
        "updated_at": "2022-02-04T14:59:51.000000Z",
        "label": "Application: ",
        "days_to_expire": 164,
        "lease": {
          "id": 258487,
          "uuid": "1a3c0110-85cb-11ec-a854-bf0fab91edae",
          "store_id": 12621,
          "pay_grade": null,
          "score": "989",
          "computation": null,
          "approved_amount": 5000,
          "comments": null,
          "employee_comments": null,
          "first_status": "V",
          "first_status_change_at": "2022-02-04T14:59:51.000000Z",
          "accepted_at": null,
          "last_activity_at": "2022-02-04T14:59:50.000000Z",
          "closed_at": null,
          "applicant_home_phone_comment": null,
          "applicant_mobile_phone_comment": null,
          "applicant_employer_phone_comment": null,
          "applicant_general_comment": null,
          "confirmation_required": 0,
          "lease_params": null,
          "updated_by_user_id": 1027,
          "created_by_user_id": 1027,
          "deleted_at": null,
          "created_at": "2022-02-04T14:59:50.000000Z",
          "updated_at": "2022-02-04T14:59:51.000000Z",
          "envelope": null,
          "loan_at": null,
          "loan": null,
          "90_day_payoff": "No",
          "cash_price": null,
          "funded_at": null,
          "funded_amount": null,
          "delivered_at": null,
          "fpd": null,
          "approved_by_user_id": null,
          "delivery_cancelled_reason": null,
          "delivery_cancelled_other": null,
          "loan_number": null,
          "ach_credit_id": null,
          "accepted_by_user_id": null,
          "envelope_id": null,
          "contract_id": null,
          "rog_at": null,
          "delivered_canceled_at": null,
          "delivered_notified_at": null,
          "e_sign_contract_url": null,
          "credits": null,
          "delivered_set_at": null,
          "uid_WorkItemId": "28842463-28ff-4c5d-85e2-ccde18b3fb11",
          "state_id": 818709,
          "sync": 0,
          "application_id": 259867,
          "state_code": "V",
          "esign_location": null,
          "option_type": null,
          "verified_at": null,
          "down_payment_taken_by_okinus": null,
          "merchant_order_id": null,
          "down_payment_in_process": 0,
          "down_payment_return_url": null,
          "send_down_payment_email": null,
          "down_payment_timestamp": null,
          "label": "1a3c0110-85cb-11ec-a854-bf0fab91edae",
          "extended": null
        }
      },
      {
        "id": 259967,
        "state_code": "V",
        "store_id": 12621,
        "created_at": "2022-02-07T20:45:01.000000Z",
        "updated_at": "2022-02-07T20:45:20.000000Z",
        "label": "Application: ",
        "days_to_expire": 167,
        "lease": {
          "id": 258587,
          "uuid": "dd295700-8856-11ec-ac92-5d48be82027e",
          "store_id": 12621,
          "pay_grade": null,
          "score": "900",
          "computation": null,
          "approved_amount": 4000,
          "comments": null,
          "employee_comments": null,
          "first_status": "V",
          "first_status_change_at": "2022-02-07T20:45:20.000000Z",
          "accepted_at": null,
          "last_activity_at": "2022-02-07T20:45:20.000000Z",
          "closed_at": null,
          "applicant_home_phone_comment": null,
          "applicant_mobile_phone_comment": null,
          "applicant_employer_phone_comment": null,
          "applicant_general_comment": null,
          "confirmation_required": 0,
          "lease_params": null,
          "updated_by_user_id": 138,
          "created_by_user_id": 138,
          "deleted_at": null,
          "created_at": "2022-02-07T20:45:20.000000Z",
          "updated_at": "2022-02-07T20:45:20.000000Z",
          "envelope": null,
          "loan_at": null,
          "loan": null,
          "90_day_payoff": "No",
          "cash_price": null,
          "funded_at": null,
          "funded_amount": null,
          "delivered_at": null,
          "fpd": null,
          "approved_by_user_id": null,
          "delivery_cancelled_reason": null,
          "delivery_cancelled_other": null,
          "loan_number": null,
          "ach_credit_id": null,
          "accepted_by_user_id": null,
          "envelope_id": null,
          "contract_id": null,
          "rog_at": null,
          "delivered_canceled_at": null,
          "delivered_notified_at": null,
          "e_sign_contract_url": null,
          "credits": null,
          "delivered_set_at": null,
          "uid_WorkItemId": "337e2ae3-3349-4638-934b-01bbc2dee14f",
          "state_id": 819006,
          "sync": 0,
          "application_id": 259967,
          "state_code": "V",
          "esign_location": null,
          "option_type": null,
          "verified_at": null,
          "down_payment_taken_by_okinus": null,
          "merchant_order_id": null,
          "down_payment_in_process": 0,
          "down_payment_return_url": null,
          "send_down_payment_email": null,
          "down_payment_timestamp": null,
          "label": "dd295700-8856-11ec-ac92-5d48be82027e",
          "extended": null
        }
      },
      {
        "id": 259968,
        "state_code": "V",
        "store_id": 12621,
        "created_at": "2022-02-07T20:51:36.000000Z",
        "updated_at": "2022-02-07T20:52:20.000000Z",
        "label": "Application: ",
        "days_to_expire": 167,
        "lease": {
          "id": 258588,
          "uuid": "d77bccc0-8857-11ec-aa7b-7f95fef4100b",
          "store_id": 12621,
          "pay_grade": null,
          "score": "5000",
          "computation": null,
          "approved_amount": 5000,
          "comments": null,
          "employee_comments": null,
          "first_status": "V",
          "first_status_change_at": "2022-02-07T20:52:19.000000Z",
          "accepted_at": null,
          "last_activity_at": "2022-02-07T20:52:20.000000Z",
          "closed_at": null,
          "applicant_home_phone_comment": null,
          "applicant_mobile_phone_comment": null,
          "applicant_employer_phone_comment": null,
          "applicant_general_comment": null,
          "confirmation_required": 0,
          "lease_params": null,
          "updated_by_user_id": 138,
          "created_by_user_id": 138,
          "deleted_at": null,
          "created_at": "2022-02-07T20:52:20.000000Z",
          "updated_at": "2022-02-07T20:52:20.000000Z",
          "envelope": null,
          "loan_at": null,
          "loan": null,
          "90_day_payoff": "No",
          "cash_price": null,
          "funded_at": null,
          "funded_amount": null,
          "delivered_at": null,
          "fpd": null,
          "approved_by_user_id": null,
          "delivery_cancelled_reason": null,
          "delivery_cancelled_other": null,
          "loan_number": null,
          "ach_credit_id": null,
          "accepted_by_user_id": null,
          "envelope_id": null,
          "contract_id": null,
          "rog_at": null,
          "delivered_canceled_at": null,
          "delivered_notified_at": null,
          "e_sign_contract_url": null,
          "credits": null,
          "delivered_set_at": null,
          "uid_WorkItemId": "1b597c00-e58a-4c19-979c-514788b417d3",
          "state_id": 819007,
          "sync": 0,
          "application_id": 259968,
          "state_code": "V",
          "esign_location": null,
          "option_type": null,
          "verified_at": null,
          "down_payment_taken_by_okinus": null,
          "merchant_order_id": null,
          "down_payment_in_process": 0,
          "down_payment_return_url": null,
          "send_down_payment_email": null,
          "down_payment_timestamp": null,
          "label": "d77bccc0-8857-11ec-aa7b-7f95fef4100b",
          "extended": null
        }
      }
    ],
    "first_page_url": "https://beta2.okinus.com/api/v1/applications/groups?applications=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://beta2.okinus.com/api/v1/applications/groups?applications=1",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://beta2.okinus.com/api/v1/applications/groups?applications=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "next_page_url": null,
    "path": "https://beta2.okinus.com/api/v1/applications/groups",
    "per_page": 15,
    "prev_page_url": null,
    "to": 3,
    "total": 3
  }
}

POST
/applications/phone-system-lookup

Phone system lookup applicant details

Parameters

Name
date_of_birth
Type
date
Description
Applicant's date of birth
Name
ssn_last_four
Type
string
Description
Last four digits of applicant's social security number
Name
zip_code
Type
string
Description
The ZIP code of the applicant

Request

POST

/applications/phone-system-lookup

POST
/applications/save-and-charge-card

Phone system save applicant's details

Parameters

Name
card_last_four
Type
date
Description
Last four digits of applicant's credit card number
Name
cvv
Type
string
Description
Credit card cvv
Name
loan_number
Type
string
Description
The applicant's loan_number
Name
amount
Type
string
Description
The amount to pay
Name
token
Type
string
Description
The token from Payliance
Name
card
Type
object
Description
The tokenized card and the verification data
Name
card_expiration
Type
string
Description
Card expiry date
Name
source_system
Type
string
Description
Source system for the charge

Request Body

Parameters to save an applicant's details

Schema: SaveCard

Request

POST

/applications/save-and-charge-card

{
  "card_last_four": "last_four_digits_of_credit_card_number_number",
  "cvv": "credit_card_cvv",
  "loan_number": "loan_number",
  "amount": "the_number_to_pay",
  "token": "token_from_payliance.",
  "card": {},
  "card_expiration": "card_expiry_date",
  "source_system": "source_system"
}

POST
/applications/lookup

Retrieve application based on lookup parameters

Returns a group of applications

Parameters

Name
last_name
Type
string
Description
Last Name
Name
date_of_birth
Type
date
Description
Applicant's date of birth
Name
social_security_number
Type
string
Description
Applicant's social security number
Name
store_id
Type
integer
Description
Store ID of the store making the request

Request

POST

/applications/lookup

Response

{
  "status": true,
  "code": 200,
  "data": {
    "application_id": 260127,
    "applicant": {
      "first_name": "nate",
      "middle_name": null,
      "last_name": "Smith"
    },
    "application_result": {
      "code": "A",
      "score": 987,
      "reason": "approved",
      "message": {
        "name": "nate Smith",
        "title": "Congratulations!",
        "options": [
          [
            "Option B",
            "$1,000.00",
            "$1.00 due at signing"
          ]
        ],
        "sub_title1": "You are approved for: "
      },
      "checkoutId": null,
      "description": "Approved",
      "offerAmounts": {
        "B": "1,000.00"
      },
      "determination": "approved",
      "application_id": 260127,
      "optionsApproved": "B",
      "coapplicant_score": null,
      "determinationMessage": "Customer has been approved"
    }
  }
}

GET
/applications/{application_id}

Retrieve Application

Parameters

Name
application_id
Type
string
Description
Application ID

Request

GET

/applications/{application_id}

Response

{
  "status": true,
  "code": 200,
  "data": {
    "id": "261391",
    "uuid": "48c9cd20-93eb-11ec-89be-edcd526f1cbf",
    "applicant": {
      "name": {
        "title": null,
        "first": "Alexander",
        "middle": null,
        "last": "test"
      },
      "email": "sample@example.com"
    },
    "coapplicant": null,
    "status_code": "V"
  }
}

POST
/applications/{uuid OR application id}/send-verification

Send the application applicant a verification code

Parameters

Name
uuid
Type
string
Description
Application ID
Name
mode
Type
string
Description
The mode of the verification. Can be either sms or email. If not supplied, defaults to sms

Request

POST

/applications/{uuid OR application id}/send-verification

Response

{
  "status": true,
  "code": 200,
  "data": "Verification code sent successfully!"
}

POST
/applications/{uuid OR application id}/confirm-verification

Confirm Verification Code

Parameters

Name
uuid
Type
string
Description
Application ID
Name
code
Type
string
Description
The code the user was sent to help verify them

Request

POST

/applications/{uuid OR application id}/confirm-verification

Response

{
  "status": true,
  "code": 200,
  "data": "Pin verified successfully!"
}

POST
/applications/contract/pdf

Get a PDF contract for an application

Get a PDF contract for an application either as base64 encoded or pdf

Request Body

Request Body parameters

Schema: Application PDF Contract

Request

POST

/applications/contract/pdf

{
  "appID": "appid",
  "version": "version",
  "language": "language",
  "dealerState": "dealer_state",
  "product": 123,
  "type": 123
}

Response

{
  "status": true,
  "code": 200,
  "data": {
    "url": "https://beta2.okinus.com/portal/system/contracts/download?path=contracts%2F261277%2Fpdf%2F1645542170.pdf"
  }
}

Schemas

Application entity

Properties

Name
store_id
Type
string
Description
Store ID for which the application is for
Name
reference_id
Type
string
Description
3rd party unique reference id or transaction id
Name
promo_code
Type
string
Description
Promotional Code
Name
threatmetrix_session_id
Type
string
Description
Threatmetrix Session ID
Name
applicant
Type
Applicant Entity
Description
Application Applicant or Co-applicant
Name
banking
Type
Banking Details
Description
Applicant Banking details
Name
co_applicant
Type
Co-Applicant Entity
Description
Application Co-applicant
Name
technician
Type
Technician
Description
Technician details

Co-Applicant Entity

Application Co-applicant

Properties

Name
title
Type
string
Description
Applicant title
Name
first_name
Type
string
Description
Applicant first name
Name
middle_name
Type
string
Description
Applicant middle name
Name
last_name
Type
string
Description
Applicant last name
Name
social_security_number
Type
string
Description
Applicant social security number
Name
date_of_birth
Type
string
Description
Applicant date of birth
Name
email
Type
string
Description
Applicant e-mail
Name
identification
Type
string
Description
ID Number of issuer
Name
identification_issuer
Type
string
Description
State where the Applicant ID was issued
Name
phone
Type
string
Description
Applicant phone number
Name
cell
Type
string
Description
Applicant cell number
Name
primaryIncome
Type
Income
Description
Applicant Income
Name
secondaryIncome
Type
Income
Description
Applicant Income

SaveCard

Applicant lookup for IVR phone system

Properties

Name
card_last_four
Type
string
Description
Last four digits of applicant's credit card number
Name
cvv
Type
string
Description
Credit card cvv
Name
loan_number
Type
string
Description
The applicant's loan_number
Name
amount
Type
string
Description
The amount to pay
Name
token
Type
string
Description
The token from Payliance
Name
card
Type
object
Description
An array of the response from verify and the card that was tokenized.
Name
card_expiration
Type
string
Description
The expiry date of the card
Name
source_system
Type
string
Description
Source system for the charge

Application PDF Contract

Get application pdf contract body

Properties

Name
appID
Type
string
Description
Application UUID
Name
version
Type
string
Description
Contract version to use
Name
language
Type
string
Description
Language of the contract
Name
dealerState
Type
string
Description
State where the store is located
Name
product
Type
integer
Description
Type of store
Name
type
Type
integer
Description
Type of contract document