Addresses API

This API allows managing the addresses associated with borrowers in the system. It provides endpoints to create, read, update, and delete addresses, as well as to handle attachments related to them.

The Address Object

The Address object represents an address in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "789e0123-f45b-67d8-a901-234567890123",
  "label": "Home",
  "street1": "Main Street 123",
  "street2": "Apartment 4B",
  "neighborhood": "Downtown",
  "city": "Example City",
  "state": "Example State",
  "zipCode": "12345",
  "reference": "In front of the park",
  "country": "MEX",
  "province": "Example Province",
  "lat": 19.4326,
  "lon": -99.1332,
  "priority": 1,
  "isHome": true,
  "isWork": false,
  "createdAt": "2023-04-01T12:00:00Z",
  "updatedAt": "2023-04-02T14:30:00Z",
  "hasAttachments": true
}

Attributes

Attribute	Description	Type
id	Unique identifier of the address	String
borrowerId	Associated borrower's ID	String
label	Descriptive label of the address	String
street1	Main line of the address	String
street2	Secondary line of the address (optional)	String
neighborhood	Neighborhood or district (optional)	String
city	City (optional)	String
state	State or region (optional)	String
zipCode	Postal code (optional)	String
reference	Additional reference (optional)	String
country	Country code (ISO3)	String
province	Province (optional)	String
lat	Latitude (optional)	Float
lon	Longitude (optional)	Float
priority	Priority of the address (optional)	Integer
isHome	Indicates if it is the home address	Boolean
isWork	Indicates if it is the work address	Boolean
createdAt	Creation date and time	String
updatedAt	Last update date and time	String
hasAttachments	Indicates if it has attachments	Boolean

Endpoints

Create a New Address

Creates a new address in the system.

POST /v1/addresses

Input Parameters:

Parameter	Description	Type	Required
borrowerId	Associated borrower's ID	String	Yes
label	Descriptive label of the address	String	No
street1	Main line of the address	String	Yes
street2	Secondary line of the address	String	No
neighborhood	Neighborhood or district	String	No
city	City	String	No
state	State or region	String	No
zipCode	Postal code	String	No
reference	Additional reference	String	No
country	Country code (ISO3)	String	Yes
province	Province	String	No
lat	Latitude	Float	No
lon	Longitude	Float	No
priority	Priority of the address	Integer	No
isHome	Indicates if it is the home address	Boolean	No
isWork	Indicates if it is the work address	Boolean	No

Request Example:

{
  "borrowerId": "789e0123-f45b-67d8-a901-234567890123",
  "label": "Office",
  "street1": "Commercial Avenue 456",
  "city": "Example City",
  "state": "Example State",
  "zipCode": "54321",
  "country": "MEX",
  "isWork": true
}

Successful Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Update an Address

Updates an existing address.

PATCH /v1/addresses/:address_id

Path Parameters:

Parameter	Description
address_id	ID of the address to update

Input Parameters:

The same as in creation, but all are optional.

Request Example:

{
  "label": "New Office",
  "street1": "Business Avenue 789",
  "zipCode": "67890"
}

Successful Response:

Returns the updated Address object.

Get an Address

Retrieves the information of a specific address.

GET /v1/addresses/:address_id

Path Parameters:

Parameter	Description
address_id	ID of the address to retrieve

Successful Response:

Returns the complete Address object.

Delete an Address

Deletes an address from the system.

DELETE /v1/addresses/:address_id

Path Parameters:

Parameter	Description
address_id	ID of the address to delete

Successful Response:

Status code 204 (No Content) if the deletion was successful.

List Addresses

Retrieves a paginated list of addresses with filtering options.

GET /v1/addresses

Query Parameters:

Parameter	Description	Type
borrower-id	Filter by borrower's ID	String
form-id	Filter by form ID	String
search	Text to search in addresses	String
page	Page number (default: 1)	Integer
per-page	Items per page (default: 10)	Integer
sort-by	Field to sort by	String
sort-direction	Sorting direction (asc or desc)	String

Successful Response:

Paginated list of Address objects.

Add an Attachment to an Address

Adds an attachment to a specific address.

POST /v1/addresses/:address_id/attachments

Path Parameters:

Parameter	Description
address_id	ID of the address to attach the file to

Input Parameters:

Parameter	Description	Type
url	URL of the attachment	String
fileExtension	File extension	String
label	Descriptive label of the file (optional)	String
metadata	Additional metadata (optional)	Object

Get Attachments of an Address

Retrieves the list of attachments of a specific address.

GET /v1/addresses/:address_id/attachments

Path Parameters:

Parameter	Description
address_id	ID of the address to get attachments from

Successful Response:

List of Attachment objects associated with the address.

Upload an Attachment to an Address

Uploads an attachment directly to a specific address.

POST /v1/addresses/:address_id/attachments/upload

Path Parameters:

Parameter	Description
address_id	ID of the address to upload the file to

Form Parameters:

Parameter	Description	Type
file	File to upload	File
label	Descriptive label of the file (optional)	String
metadata	Additional metadata in JSON format (optional)	String

Delete an Attachment from an Address

Deletes a specific attachment from an address.

DELETE /v1/addresses/:address_id/attachments/:attachment_id

Path Parameters:

Parameter	Description
address_id	ID of the address
attachment_id	ID of the attachment to delete

Successful Response:

Status code 204 (No Content) if the deletion was successful.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page