Skip to main content
POST
/
v1
/
loans
/
{applicationId}
/
guarantor
Add Guarantor
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/loans/{applicationId}/guarantor \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "first_name": "John",
  "last_name": "Doe",
  "phone": "08012345678",
  "email": "guarantor@example.com"
}
'
{
  "status": "success",
  "data": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "phone": "08012345678",
    "email": "guarantor@example.com"
  }
}

​
Overview

Adds a guarantor to the loan. The guarantor will receive an invitation via the clientPath link to complete their form. This step is optional unless required by the underwriting decision.

​
Request

Method: POST
URL: /v1/loans/:applicationId/guarantor

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.
applicationIdPathstringYesApplication ID.

​
Request Body

{
  "first_name": "Bola",
  "last_name": "Akin",
  "phone": "08099887766",
  "email": "bola.akin@example.com"
}
FieldTypeRequiredDescription
first_namestringYesGuarantor’s first name
last_namestringYesGuarantor’s last name
phonestringYesValid Nigerian phone number
emailstringYesValid email address

​
Response

​
201 Created

{
  "status": "success",
  "data": {
    "id": 7,
    "firstName": "Bola",
    "lastName": "Akin",
    "phoneNumber": "08099887766",
    "emailAddress": "bola.akin@example.com",
    "clientPath": "https://app.carbon.ng/guarantor",
    "loanOfferId": 42,
    "tokenExpiresAt": "2025-01-22T10:00:00.000Z",
    "inviteSentAt": null,
    "submittedAt": null
  }
}
FieldDescription
clientPathLink sent to the guarantor to complete their form
tokenExpiresAtExpiry of the guarantor invite link
submittedAtPopulated when the guarantor completes the form

​
Error Responses

StatusMessageCause
400first_name is requiredField missing
400last_name is requiredField missing
400phone must be a valid Nigerian numberInvalid or missing phone
400email must be a valid email addressInvalid or missing email
400Application not foundInvalid applicationId
422Application has no loan IDApplication not yet registered

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Path Parameters

​
applicationId
string
required

Body

application/json

Provide the required values for the request body.

​
first_name
string
required
Example:

"John"

​
last_name
string
required
Example:

"Doe"

​
phone
string
required
Example:

"08012345678"

​
email
string
required
Example:

"guarantor@example.com"

Response

200 - application/json

Successful response

The response is of type object.