Applications

Applications represent loan applications, credit applications, or other forms submitted by contacts. They are linked to contacts and can be tracked through various statuses. On this page, we will dive into the different application endpoints you can use to manage applications programmatically.

POST/api/applications/list

List all applications

This endpoint allows you to retrieve a paginated list of all applications with advanced filtering options.

Optional body parameters

Name
page
Type
integer
Description
Page number for pagination (default: 1).
Name
size
Type
integer
Description
Number of applications per page (default: 10).
Name
search
Type
string
Description
Search by application name (case-insensitive).
Name
contactId
Type
string
Description
Filter by contact ID.
Name
status
Type
string
Description
Filter by application status.
Name
userId
Type
string
Description
Filter by assigned user ID.

Request

POST

/api/applications/list

curl -X POST https://your-tether-instance.com/api/applications/list \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "size": 10,
    "search": "loan",
    "status": "pending"
  }'

Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Auto Loan Application",
      "status": "pending",
      "contactId": {
        "_id": "507f1f77bcf86cd799439012",
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumber": "+1234567890",
        "email": "john.doe@example.com"
      },
      "userId": {
        "_id": "507f1f77bcf86cd799439013",
        "fullName": "Jane Smith",
        "email": "jane@company.com"
      },
      "organizationId": "507f1f77bcf86cd799439014",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 45,
  "page": 1,
  "size": 10
}

GET/api/applications

Get applications by query

This endpoint allows you to retrieve applications using query parameters. Returns all matching applications without pagination.

Optional query parameters

Name
contactId
Type
string
Description
Filter by contact ID.
Name
status
Type
string
Description
Filter by application status.
Name
search
Type
string
Description
Search by application name.
Name
userId
Type
string
Description
Filter by assigned user ID.

Request

GET

/api/applications

curl -G https://your-tether-instance.com/api/applications \
  -H "Authorization: Bearer {token}" \
  -d contactId=507f1f77bcf86cd799439012 \
  -d status=approved

Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Auto Loan Application",
      "status": "approved",
      "contactId": {
        "_id": "507f1f77bcf86cd799439012",
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumber": "+1234567890",
        "email": "john.doe@example.com"
      },
      "userId": {
        "_id": "507f1f77bcf86cd799439013",
        "fullName": "Jane Smith",
        "email": "jane@company.com"
      },
      "organizationId": "507f1f77bcf86cd799439014",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z"
    }
  ],
  "total": 1
}

POST/api/applications

Create an application

This endpoint allows you to create a new application linked to a contact.

Required attributes

Name
contactId
Type
string
Description
The ID of the contact this application belongs to.
Name
name
Type
string
Description
The name/title of the application.
Name
status
Type
string
Description
The initial status of the application.

Optional attributes

Name
userId
Type
string
Description
The ID of the user to assign. Defaults to the authenticated user.

Request

POST

/api/applications

curl -X POST https://your-tether-instance.com/api/applications \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "507f1f77bcf86cd799439012",
    "name": "Auto Loan Application",
    "status": "pending"
  }'

Response

{
  "success": true,
  "message": "Application created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "contactId": "507f1f77bcf86cd799439012",
    "organizationId": "507f1f77bcf86cd799439014",
    "name": "Auto Loan Application",
    "status": "pending",
    "userId": "507f1f77bcf86cd799439013",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

GET/api/applications/:id

Retrieve an application

This endpoint allows you to retrieve a single application by its ID. The response includes populated contact and user information.

Request

GET

/api/applications/:id

curl https://your-tether-instance.com/api/applications/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Auto Loan Application",
    "status": "approved",
    "contactId": {
      "_id": "507f1f77bcf86cd799439012",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+1234567890",
      "email": "john.doe@example.com"
    },
    "userId": {
      "_id": "507f1f77bcf86cd799439013",
      "fullName": "Jane Smith",
      "email": "jane@company.com"
    },
    "organizationId": "507f1f77bcf86cd799439014",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  }
}

PUT/api/applications/:id

Update an application

This endpoint allows you to update an existing application. Any organization user can update applications within their organization.

Optional attributes

Name
name
Type
string
Description
Updated application name.
Name
status
Type
string
Description
Updated application status.
Name
userId
Type
string
Description
Reassign the application to a different user.
Name
fromHistoryModal
Type
boolean
Description
If true, clears field change history for the updated fields.

Request

PUT

/api/applications/:id

curl -X PUT https://your-tether-instance.com/api/applications/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Auto Loan Application",
    "status": "approved"
  }'

Response

{
  "success": true,
  "message": "Application updated successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Updated Auto Loan Application",
    "status": "approved",
    "contactId": {
      "_id": "507f1f77bcf86cd799439012",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+1234567890",
      "email": "john.doe@example.com"
    },
    "userId": {
      "_id": "507f1f77bcf86cd799439013",
      "fullName": "Jane Smith",
      "email": "jane@company.com"
    },
    "organizationId": "507f1f77bcf86cd799439014",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T14:00:00.000Z"
  }
}

DELETE/api/applications/:id

Delete an application

This endpoint allows you to delete an application. Any organization user can delete applications within their organization.

Request

DELETE

/api/applications/:id

curl -X DELETE https://your-tether-instance.com/api/applications/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Application deleted successfully"
}

Error responses

Common error responses you may encounter when using the Applications API.

400 Bad Request

Returned when required fields are missing or invalid.

404 Not Found

Returned when the application or contact does not exist, or doesn't belong to your organization.

500 Internal Server Error

Returned when an unexpected error occurs on the server.

400 - Missing fields

{
  "success": false,
  "message": "Missing required fields",
  "error": "contactId, name, and status are required"
}

404 - Not found

{
  "success": false,
  "message": "Application not found"
}

404 - Contact not found

{
  "success": false,
  "message": "Contact not found",
  "error": "Contact does not exist or does not belong to this organization"
}

500 - Server error

{
  "success": false,
  "message": "Failed to create application",
  "error": "Unknown error occurred"
}

Real-time events

Applications emit socket events for real-time updates. Subscribe to these events to keep your UI in sync.

Name
application_created
Type
event
Description
Emitted when a new application is created. Payload: {application}.
Name
application_updated
Type
event
Description
Emitted when an application is updated. Payload: {application}.
Name
application_deleted
Type
event
Description
Emitted when an application is deleted. Payload: {applicationId}.