aVenture APIEntity Addresses Canonical

Create entity address

View as Markdown

Create or reuse an entity address from structured address fields and attach it to the entity. fullAddress is server-synthesized and cannot be written; city-level rows require researchExhausted=true after address research is exhausted. The first current address defaults to current domicile and dominant associations; later omitted-role addresses stay unclassified.

Authentication

AuthorizationBearer

User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key

OR
X-API-Keystring

Admin API key for system-to-system write operations

Path parameters

entityIdstringRequiredformat: "uuid"
Canonical entity UUID

Query parameters

sourceTypeenumRequired
Write provenance source type.
sourceDetailstringRequired
Source detail or reviewer reference for the write.
sourceProviderstringOptional

Provider name for provider-native IDs or slugs.

sourceProviderIdstringOptional

Provider-native source ID.

sourceProviderSlugstringOptional

Provider-native source slug.

actorTypeenumOptional

Actor type; inferred as agent when agentChassis and agentModel are supplied, or as employee from an authenticated user JWT session.

Allowed values:
agentChassisstringOptional

Agent chassis token for agent-authored writes.

agentModelstringOptional

Agent model id for agent-authored writes.

Request

This endpoint expects an object.
addressLine1string or nullOptional0-255 characters
Address line 1.
addressLine2string or nullOptional0-100 characters

Address line 2 (suite, floor, etc.)

cityNamestring or nullOptional0-200 characters

City name, resolved within the selected country; include state or region only when that country requires it.

countryCodestring or nullOptional=2 characters

ISO-3166 alpha-2 country code.

countryNamestring or nullOptional
Country name lookup.
endDatedate or nullOptional
Last known day this address association applied.
latitudedouble or nullOptional
Latitude in decimal degrees
longitudedouble or nullOptional
Longitude in decimal degrees
postalCodestring or nullOptional0-20 characters
Postal or ZIP code.
researchExhaustedboolean or nullOptional

Allow a city-level or coarser row only when source research proves no address-line, postal, or coordinate-specific address exists.

roleenum or nullOptional

Address association role. Domicile is a legal or registered seat, dominant is the predominant display location, origin is a founding or historical location; null means unclassified.

startDatedate or nullOptional
First known day this address association applied.
stateAbbrevstring or nullOptional0-20 characters
State or region abbreviation for countries that require one.
stateNamestring or nullOptional0-50 characters
State or region name, resolved within the selected country when that country requires one.
isCurrentboolean or nullOptionalDeprecated
Deprecated legacy flag marking whether the address is currently in use.
isHqboolean or nullOptionalDeprecated
Deprecated compatibility flag for a legal or registered seat.
isPrimaryboolean or nullOptionalDeprecated
Deprecated compatibility flag for the predominant display location.

Response

OK
addressinteger or nullOptional
Legacy address row identifier
addressLine1string or nullOptional
addressLine2string or nullOptional
associationlist of objectsOptional

Role-period associations for this physical address

cityobject or nullOptional
City reference
countryobject or nullOptional
Country reference
countryAbbrevstring or nullOptional
createdAtdatetime or nullOptional
fullAddressstring or nullOptional

Single-line formatted address

idinteger or nullOptional
Address record identifier
latitudedouble or nullOptional
longitudedouble or nullOptional
postalCodestring or nullOptional
stateobject or nullOptional
State or region reference
stateAbbrevstring or nullOptional
streetstring or nullOptional
updatedAtdatetime or nullOptional
isCurrentboolean or nullOptionalDeprecated

Deprecated aggregate compatibility flag; true when any association is current

isHqboolean or nullOptionalDeprecated

Deprecated legacy flag marking the headquarters or legal/registered address

isPrimaryboolean or nullOptionalDeprecated
Deprecated legacy flag marking the primary display address

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
406
Not Acceptable Error
409
Conflict Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error