Skip to main content

Addresses

5 API calls in this section.

Create Address​

Platform & Access / Addresses
POST/addresses?language=en

Creates a new address in the system, or returns a normalized address JSON when save_to_address_book=false. Key rules: - JSON-first: lat/long/country/contact_info should be included. - save_to_address_book=false returns normalized JSON (no DB insert). - save_to_address_book=true (default) persists the address and returns the row. Required Fields: - address_type, country, latitude, longitude Owner Constraint: - Provide either user_id or tenant_id.

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request POST "$ONDI_BASE_URL/addresses?language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "address_type": "user",7  "user_id": "{{user_id}}",8  "title": {9    "en": "Home Address"10  },11  "full_address": "123 Main St, Anytown, CA 12345",12  "address_line1": "123 Main St",13  "address_line2": "Apt 4B",14  "street": "Main St",15  "building": "123",16  "floor": "4",17  "apartment": "4B",18  "city": "Anytown",19  "state": "CA",20  "country": "United States",21  "country_code": "USA",22  "postal_code": "12345",23  "latitude": 37.7749,24  "longitude": -122.4194,25  "contact_info": {26    "phone": "+123456789",27    "email": "a@example.com"28  },29  "save_to_address_book": false30}'
Request body
json
1{2  "address_type": "user",3  "user_id": "{{user_id}}",4  "title": {5    "en": "Home Address"6  },7  "full_address": "123 Main St, Anytown, CA 12345",8  "address_line1": "123 Main St",9  "address_line2": "Apt 4B",10  "street": "Main St",11  "building": "123",12  "floor": "4",13  "apartment": "4B",14  "city": "Anytown",15  "state": "CA",16  "country": "United States",17  "country_code": "USA",18  "postal_code": "12345",19  "latitude": 37.7749,20  "longitude": -122.4194,21  "contact_info": {22    "phone": "+123456789",23    "email": "a@example.com"24  },25  "save_to_address_book": false26}

Query parameters

languageOptional
query string

en

Language of the response

Request body fields

address_typeExample
string

Example field from the request body.

user_idExample
string

Example field from the request body.

titleExample
object

Example field from the request body.

title.enExample
string

Example field from the request body.

full_addressExample
string

Example field from the request body.

address_line1Example
string

Example field from the request body.

address_line2Example
string

Example field from the request body.

streetExample
string

Example field from the request body.

buildingExample
string

Example field from the request body.

floorExample
string

Example field from the request body.

apartmentExample
string

Example field from the request body.

cityExample
string

Example field from the request body.

stateExample
string

Example field from the request body.

countryExample
string

Example field from the request body.

country_codeExample
string

Example field from the request body.

postal_codeExample
string

Example field from the request body.

latitudeExample
number

Example field from the request body.

longitudeExample
number

Example field from the request body.

contact_infoExample
object

Example field from the request body.

contact_info.phoneExample
string

Example field from the request body.

contact_info.emailExample
string

Example field from the request body.

save_to_address_bookExample
boolean

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response201Created
Response body
json
1{2  "success": true,3  "message": "Address created successfully",4  "address": {5    "id": "uuid-example",6    "user_id": "user-uuid",7    "tenant_id": null,8    "address_type": "user",9    "title": {10      "en": "Home Address"11    },12    "city": "Anytown",13    "country": "United States",14    "created_at": "2023-01-01T12:00:00Z",15    "updated_at": "2023-01-01T12:00:00Z"16  }17}
Error - Missing Required Fields400Bad Request
Response body
json
1{2  "success": false,3  "message": "Missing required fields"4}
Error - Invalid Address Type400Bad Request
Response body
json
1{2  "success": false,3  "message": "Invalid address type"4}
Error - Owner Constraint Violation400Bad Request
Response body
json
1{2  "success": false,3  "message": "Address must belong to either user or tenant, not both"4}
Error - Unauthorized403Forbidden
Response body
json
1{2  "success": false,3  "message": "Unauthorized"4}

Get Address​

Platform & Access / Addresses
GET/addresses/:addressId?language=en

Retrieves a specific address by ID. Path Parameters: - addressId: UUID of the address to retrieve Authentication: - Requires valid authentication token - Users can only access their own addresses - Users can access addresses of tenants they belong to - System admins can access any address Response: - Returns the complete address object with all fields - Returns 404 if address not found - Returns 403 if user is not authorized to access the address

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/addresses/:addressId?language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

addressIdRequired
path string

ID of the address to retrieve

Query parameters

languageOptional
query string

en

Language of the response

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

Success Response200OK
Response body
json
1{2  "success": true,3  "message": "Address retrieved successfully",4  "address": {5    "id": "uuid-example",6    "user_id": "user-uuid",7    "tenant_id": null,8    "address_type": "user",9    "is_primary": true,10    "title": {11      "en": "Home Address"12    },13    "full_address": "123 Main St, Anytown, CA 12345",14    "address_line1": "123 Main St",15    "address_line2": "Apt 4B",16    "street": "Main St",17    "building": "123",18    "floor": "4",19    "apartment": "4B",20    "city": "Anytown",21    "state": "CA",22    "country": "United States",23    "country_code": "USA",24    "postal_code": "12345",25    "latitude": 37.7749,26    "longitude": -122.4194,27    "is_billing": false,28    "is_shipping": true,29    "is_active": true,30    "metadata": {31      "delivery_instructions": "Leave at front door",32      "landmark": "Blue house with white fence",33      "is_verified": false,34      "verification_date": null35    },36    "created_at": "2023-01-01T12:00:00Z",37    "updated_at": "2023-01-01T12:00:00Z"38  }39}
Error - Address Not Found404Not Found
Response body
json
1{2  "success": false,3  "message": "Address not found"4}
Error - Unauthorized403Forbidden
Response body
json
1{2  "success": false,3  "message": "Unauthorized"4}

List Addresses​

Platform & Access / Addresses
GET/addresses?page=1&limit=10&userId=&tenantId=&addressType=&search=&language=en

Lists addresses with pagination and filtering options. Query Parameters: - page: Page number for pagination (default: 1) - limit: Number of items per page (default: 10) - userId: Filter addresses by user ID - tenantId: Filter addresses by tenant ID (or from auth context) - addressType: Filter by address type (user, tenant, branch, warehouse, customer, pickup, delivery) - search: Search term to filter addresses by full_address field Authentication & Scope: - No role: own addresses only - tenant_admin + tenantId: returns all addresses from all tenant_admin users of that tenant - userId param: filter to specific user's addresses - System admins can see all addresses Response: - Returns a paginated list of addresses - Includes pagination metadata (page, limit, total)

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/addresses?page=1&limit=10&userId=&tenantId=&addressType=&search=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Query parameters

pageOptional
query string

1

Page number for pagination (default: 1)

limitOptional
query string

10

Number of items per page (default: 10)

userIdOptional
query string

Filter addresses by user ID

tenantIdOptional
query string

Filter addresses by tenant ID

addressTypeOptional
query string

Filter by address type (user, tenant, branch, warehouse, customer, pickup, delivery)

searchOptional
query string

Search term to filter addresses by full_address field

languageOptional
query string

en

Language of the response

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

Success Response200OK
Response body
json
1{2  "success": true,3  "message": "Addresses retrieved successfully",4  "addresses": [5    {6      "id": "uuid-example-1",7      "user_id": "user-uuid",8      "tenant_id": null,9      "address_type": "user",10      "title": {11        "en": "Home Address"12      },13      "city": "Anytown",14      "country": "United States",15      "created_at": "2023-01-01T12:00:00Z",16      "updated_at": "2023-01-01T12:00:00Z"17    },18    {19      "id": "uuid-example-2",20      "user_id": "user-uuid",21      "tenant_id": null,22      "address_type": "user",23      "title": {24        "en": "Work Address"25      },26      "city": "Business City",27      "country": "United States",28      "created_at": "2023-01-02T12:00:00Z",29      "updated_at": "2023-01-02T12:00:00Z"30    }31  ],32  "page": 1,33  "limit": 10,34  "total": 235}

Update Address​

Platform & Access / Addresses
PUT/addresses/:addressId?language=en

Updates an existing address. Path Parameters: - addressId: UUID of the address to update Updatable Fields: - address_type: Type of address (must be one of: 'user', 'tenant', 'branch', 'warehouse', 'customer', 'pickup', 'delivery') - title: Title/name for this address (JSONB object with language keys) - full_address: Complete formatted address as a single text field - city: City name - country: Country name - address_line1: First line of the address (e.g., street address) - address_line2: Second line of the address (e.g., apartment, suite) - street: Street name - building: Building name or number - floor: Floor number or name - apartment: Apartment or unit number - latitude: Geographic latitude for mapping - longitude: Geographic longitude for mapping - is_default: Flag indicating if this is the default address - is_active: Flag indicating if this address is currently active Authentication: - Requires valid authentication token - Users can only update their own addresses - Users can update addresses of tenants they are admins for - System admins can update any address Note: - You cannot change the owner (user_id or tenant_id) of an address - Only fields included in the request will be updated

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request PUT "$ONDI_BASE_URL/addresses/:addressId?language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "title": {7    "en": "Updated Home Address"8  },9  "address_line1": "456 New St",10  "city": "New City",11  "country": "United States",12  "is_primary": true13}'
Request body
json
1{2  "title": {3    "en": "Updated Home Address"4  },5  "address_line1": "456 New St",6  "city": "New City",7  "country": "United States",8  "is_primary": true9}

Path parameters

addressIdRequired
path string

ID of the address to update

Query parameters

languageOptional
query string

en

Language of the response

Request body fields

titleExample
object

Example field from the request body.

title.enExample
string

Example field from the request body.

address_line1Example
string

Example field from the request body.

cityExample
string

Example field from the request body.

countryExample
string

Example field from the request body.

is_primaryExample
boolean

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response200OK
Response body
json
1{2  "success": true,3  "message": "Address updated successfully",4  "address": {5    "id": "uuid-example",6    "user_id": "user-uuid",7    "tenant_id": null,8    "address_type": "user",9    "title": {10      "en": "Updated Home Address"11    },12    "address_line1": "456 New St",13    "city": "New City",14    "country": "United States",15    "is_primary": true,16    "created_at": "2023-01-01T12:00:00Z",17    "updated_at": "2023-01-03T15:30:00Z"18  }19}
Error - Address Not Found404Not Found
Response body
json
1{2  "success": false,3  "message": "Address not found"4}
Error - Unauthorized403Forbidden
Response body
json
1{2  "success": false,3  "message": "Unauthorized"4}

Delete Address​

Platform & Access / Addresses
DELETE/addresses/:addressId?language=en

Deletes an address by ID. Path Parameters: - addressId: UUID of the address to delete Authentication: - Requires valid authentication token - Users can only delete their own addresses - Users can delete addresses of tenants they are admins for - System admins can delete any address Response: - Returns success message on successful deletion - Returns 404 if address not found - Returns 403 if user is not authorized to delete the address

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request DELETE "$ONDI_BASE_URL/addresses/:addressId?language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

addressIdRequired
path string

ID of the address to delete

Query parameters

languageOptional
query string

en

Language of the response

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

Success Response200OK
Response body
json
1{2  "success": true,3  "message": "Address deleted successfully"4}
Error - Address Not Found404Not Found
Response body
json
1{2  "success": false,3  "message": "Address not found"4}
Error - Unauthorized403Forbidden
Response body
json
1{2  "success": false,3  "message": "Unauthorized"4}