{"openapi":"3.1.0","info":{"title":"Addresses API","version":"0.1.0","description":"The platform's registry of verified addresses (`docs/addresses.md`), shared by every organization: an address once normalised, geocoded and verified is a platform address (`pad_`) any order, customer, company location or site can reference. The registry holds addresses only — never who lives there, which organization used one, or when — and every answer is the same whoever asks."},"paths":{"/addresses/suggest":{"get":{"tags":["addresses"],"operationId":"addresses.suggest","parameters":[{"name":"q","in":"query","schema":{"type":"string","allOf":[{"allOf":[{"minLength":3},{"maxLength":200}],"description":"what has been typed of the address line, at least three characters"}]},"required":true,"example":"200 Collins"},{"name":"country","in":"query","schema":{"$ref":"#/components/schemas/CountryCode"},"required":false,"example":"AU"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"AddressSuggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSuggestionsEncoded"},"examples":{"contract":{"summary":"addresses.suggest","value":{"items":[{"countryCode":"AU","streetNumber":"200","streetName":"COLLINS","streetType":"ST","locality":"MELBOURNE","region":"VIC","postcode":"3000","street":"200 Collins Street","lines":["200 Collins Street","Melbourne VIC 3000"],"geocode":{"latitude":-37.8152,"longitude":144.9671,"precision":"rooftop"}}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"422":{"description":"CountryNotSupported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryNotSupportedEncoded"}}}},"503":{"description":"AddressProviderUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AddressProviderUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"Suggest addresses for what has been typed of an address line (`q`, at least three characters) in a country (`country`, ISO 3166-1 alpha-2, AU when absent): canonical forms — or, outside Australia, the provider's lines — with where each is when known, best first (`limit`: default 5, at most 10). A suggestion is not yet a platform address — verify the one picked with `POST /addresses/verify`. 422 `CountryNotSupported` for a country no provider covers here; 503 `AddressProviderUnavailable` when the provider does not answer. The answer is the address alone — the same whether or not anyone verified it before — and nothing about who else uses it. Appends nothing: a read.\n\nRequires `orders:read` or `customers:read` or `companies:read` or `locations:read` or `purchasing:read`.","x-mcp-withheld":"Suggestions for an address line as a person types it, a keystroke at a time; an agent sends the whole address to addresses_verify_address, which answers the nearest known addresses when it cannot verify one.","x-required-scopes":["orders:read","customers:read","companies:read","locations:read","purchasing:read"],"x-example-source":{"origin":"contract"}}},"/addresses/verify":{"post":{"tags":["addresses"],"operationId":"addresses.verify","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"AddressVerified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressVerifiedEncoded"},"examples":{"contract":{"summary":"addresses.verify","value":{"address":{"id":"pad_5d81a0c2-9e3b-4f17-a6d4-2c8e0b7f9a31","countryCode":"AU","streetNumber":"200","streetName":"COLLINS","streetType":"ST","locality":"MELBOURNE","region":"VIC","postcode":"3000","street":"200 Collins Street","lines":["Level 4, 200 Collins Street","Melbourne VIC 3000"],"geocode":{"latitude":-37.8152,"longitude":144.9671,"precision":"rooftop"},"unit":"LEVEL 4","buildingId":"pad_0b3f6c1e-4a7d-8e29-9c51-7f2d4e8a6b10","verification":"platform-verified","confidence":{"score":0.6,"level":"probable"}},"building":{"id":"pad_0b3f6c1e-4a7d-8e29-9c51-7f2d4e8a6b10","countryCode":"AU","streetNumber":"200","streetName":"COLLINS","streetType":"ST","locality":"MELBOURNE","region":"VIC","postcode":"3000","street":"200 Collins Street","lines":["200 Collins Street","Melbourne VIC 3000"],"geocode":{"latitude":-37.8152,"longitude":144.9671,"precision":"rooftop"},"verification":"platform-verified","confidence":{"score":0.9,"level":"verified"}}}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"422":{"description":"AddressUnverified | CountryNotSupported","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AddressUnverifiedEncoded"},{"$ref":"#/components/schemas/CountryNotSupportedEncoded"}]}}}},"503":{"description":"AddressProviderUnavailable | RequestLogUnavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AddressProviderUnavailableEncoded"},{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}]}}}}},"description":"Normalise, verify and geocode one address as it was typed: the platform address it is, down to the unit (`Unit 3`, `Level 4`, read from either line) — put its `pad_` id on the tenant's record as `verifiedAddressId` — and, for a unit, its `building`, the record routing and zones group by. Each carries its `confidence`: a score from 0 to 1 that rises with the official sources, carriers and customers that confirmed it (`verified` from 0.85, `probable` from 0.6). An address nothing can verify is 422 `AddressUnverified` with how it was read and the nearest addresses known, and is not stored; 422 `CountryNotSupported`; 503 `AddressProviderUnavailable`. Appends `addresses.address-registered` the first time an address (and a unit's building) is verified, under the registry's own actor — never the caller's. Idempotent by content: the id is derived from the normalised address, so verifying it again, by anyone, answers the same record and appends nothing. The answer is the address alone — the same whether or not anyone verified it before — and nothing about who else uses it.\n\nRequires `orders:write` or `customers:write` or `companies:write` or `locations:write` or `purchasing:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyAddressEncoded"},"example":{"address1":"Level 4, 200 Collins Street","city":"Melbourne","provinceCode":"VIC","zip":"3000","countryCode":"AU"}}},"required":true},"x-mcp-tool":{"name":"addresses_verify_address","title":"Addresses: Verify address","toolset":"crm","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["orders:write","customers:write","companies:write","locations:write","purchasing:write"],"x-example-source":{"origin":"contract"}}},"/addresses":{"get":{"tags":["addresses"],"operationId":"addresses.list","parameters":[{"name":"ids","in":"query","schema":{"type":"string"},"required":true,"example":"pad_5d81a0c2-9e3b-4f17-a6d4-2c8e0b7f9a31,pad_0b3f6c1e-4a7d-8e29-9c51-7f2d4e8a6b10"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"PlatformAddressPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformAddressPageEncoded"},"examples":{"contract":{"summary":"addresses.list","value":{"items":[{"id":"pad_5d81a0c2-9e3b-4f17-a6d4-2c8e0b7f9a31","countryCode":"AU","streetNumber":"200","streetName":"COLLINS","streetType":"ST","locality":"MELBOURNE","region":"VIC","postcode":"3000","street":"200 Collins Street","lines":["Level 4, 200 Collins Street","Melbourne VIC 3000"],"geocode":{"latitude":-37.8152,"longitude":144.9671,"precision":"rooftop"},"unit":"LEVEL 4","buildingId":"pad_0b3f6c1e-4a7d-8e29-9c51-7f2d4e8a6b10","verification":"platform-verified","confidence":{"score":0.6,"level":"probable"}},{"id":"pad_0b3f6c1e-4a7d-8e29-9c51-7f2d4e8a6b10","countryCode":"AU","streetNumber":"200","streetName":"COLLINS","streetType":"ST","locality":"MELBOURNE","region":"VIC","postcode":"3000","street":"200 Collins Street","lines":["200 Collins Street","Melbourne VIC 3000"],"geocode":{"latitude":-37.8152,"longitude":144.9671,"precision":"rooftop"},"verification":"platform-verified","confidence":{"score":0.9,"level":"verified"}}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Platform addresses by id (`ids`, at most 100) — the canonical form, coordinates, building and confidence a tenant's record references by `verifiedAddressId`: what routing measures distance with and a badge shows. An id the registry does not hold is left out. Appends nothing: a read.\n\nRequires `orders:read` or `customers:read` or `companies:read` or `locations:read` or `purchasing:read`.","x-mcp-withheld":"Platform addresses by id, for routing's distances and the admin's verified badge; addresses_verify_address answers the platform address whole, and a record's address carries it.","x-required-scopes":["orders:read","customers:read","companies:read","locations:read","purchasing:read"],"x-example-source":{"origin":"contract"}}},"/events":{"get":{"tags":["events"],"operationId":"events.list","parameters":[{"name":"since","in":"query","schema":{"type":"string"},"required":false,"example":"1"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"500"},{"name":"upTo","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/addresses.address-registeredEncoded"}]}},"examples":{"contract":{"summary":"events.list","value":[{"_tag":"addresses.address-registered","eventId":"evt_01a1c0de-2a00-7b10-8c20-3d4e5f6a7b80","txId":"tx_01a1c0de-2a00-7b10-8c20-3d4e5f6a7b81","tenantId":"org_00000000-0000-0000-0000-000000000000","sequence":1,"occurredAt":"2026-10-29T02:10:00.000Z","source":"address-manager","version":1,"actor":{"_tag":"system","id":"address-manager:registry"},"correlationId":"tx_01a1c0de-2a00-7b10-8c20-3d4e5f6a7b81","payload":{"address":{"id":"pad_0b3f6c1e-4a7d-8e29-9c51-7f2d4e8a6b10","countryCode":"AU","streetNumber":"200","streetName":"COLLINS","streetType":"ST","locality":"MELBOURNE","region":"VIC","postcode":"3000","street":"200 Collins Street","lines":["200 Collins Street","Melbourne VIC 3000"],"geocode":{"latitude":-37.8152,"longitude":144.9671,"precision":"rooftop"},"verification":"platform-verified","confidence":{"score":0.9,"level":"verified"}},"key":"AU|200|COLLINS|ST|MELBOURNE|VIC|3000|","evidence":[{"source":"provider","name":"fake","matched":"address","checkedAt":"2026-10-29T02:10:00.000Z"}]}}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Replay committed registry events at-or-after `since` (a journal sequence number), oldest first: every address the registry learned — buildings and units — with its canonical form, coordinates and the source that verified it. The registry is the platform's, so its facts are the platform organization's: any other organization replays an empty journal. One response is a page: `limit` defaults to 500 and is capped at 5000 (an over-cap request is clamped). Pages are `sequence`-ordered and the boundary is stable — repeat with `since=<last event's sequence + 1>` until a page comes back smaller than `limit` to replay the journal exactly once. `upTo` (inclusive) ends the replay at a sequence instead of the journal's head — with `GET /events/head` it replays the journal as it stood at a moment. Appends nothing: a read of facts already journalled.\n\nRequires `activity:read`.","x-mcp-withheld":"The journal replay a consumer pages through to build its projection; agents read the projections the list and get tools serve, and the audit trail (`audit_trail`) for history.","x-required-scopes":["activity:read"],"x-example-source":{"origin":"contract"}}},"/events/head":{"get":{"tags":["events"],"operationId":"events.head","parameters":[{"name":"at","in":"query","schema":{"type":"string"},"required":true,"example":"2026-10-29T03:00:00.000Z"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Where a tenant's journal stood at a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalHead"},"examples":{"contract":{"summary":"events.head","value":{"at":"2026-10-29T03:00:00.000Z","sequence":1}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The journal's position at a moment: the last `sequence` the database had recorded for this tenant at `at` (absent when it held nothing yet), by the database's own clock rather than the service's. Replaying with `upTo=<sequence>` then gives the journal exactly as it stood then; a set of heads taken at one `at` is a consistent cut across journals. Appends nothing: a read of facts already journalled.\n\nRequires `activity:read`.","x-mcp-withheld":"Where a journal stood at a moment, for a consumer cutting journals to replay them as of then; agents read history through the audit trail (`audit_trail`).","x-required-scopes":["activity:read"],"x-example-source":{"origin":"contract"}}}},"components":{"schemas":{"CountryCode":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2, upper case"},"GeocodePrecision":{"type":"string","enum":["rooftop","street","locality","postcode"],"description":"What a geocode points at, finest first: `rooftop` (the building), `street` (interpolated along the street), `locality` (the suburb's centre), `postcode` (the postcode area's centre)."},"Geocode":{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"longitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"precision":{"$ref":"#/components/schemas/GeocodePrecision"}},"required":["latitude","longitude","precision"],"additionalProperties":false},"AddressCandidate":{"type":"object","properties":{"countryCode":{"$ref":"#/components/schemas/CountryCode"},"unit":{"type":"string","maxLength":200},"streetNumber":{"type":"string","maxLength":200},"streetName":{"type":"string","maxLength":200},"streetType":{"type":"string","maxLength":200},"locality":{"type":"string","maxLength":200},"region":{"type":"string","maxLength":200},"postcode":{"type":"string","maxLength":200},"street":{"type":"string","maxLength":200},"lines":{"type":"array","items":{"type":"string","maxLength":200}},"geocode":{"$ref":"#/components/schemas/Geocode"}},"required":["countryCode","street","lines"],"additionalProperties":false},"AddressSuggestionsEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AddressCandidate"}}},"required":["items"],"additionalProperties":false},"CountryNotSupportedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["CountryNotSupported"]},"countryCode":{"type":"string"}},"required":["_tag","countryCode"],"additionalProperties":false},"AddressProviderUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AddressProviderUnavailable"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"RequestLogUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["RequestLogUnavailable"]},"tokenId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","tokenId","reason"],"additionalProperties":false},"UnauthorizedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["Unauthorized"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"TokenAlreadyUsedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TokenAlreadyUsed"]},"tokenId":{"type":"string"}},"required":["_tag","tokenId"],"additionalProperties":false},"TenantRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TenantRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"ScopeRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ScopeRequired"]},"required":{"type":"array","items":{"type":"string"}}},"required":["_tag","required"],"additionalProperties":false},"PlatformAdminRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["PlatformAdminRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"SubscriptionRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SubscriptionRequired"]},"status":{"type":"string"}},"required":["_tag","status"],"additionalProperties":false},"MirroredFromSourceEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["MirroredFromSource"]},"source":{"type":"string"}},"required":["_tag","source"],"additionalProperties":false},"VerifyAddressEncoded":{"type":"object","properties":{"address1":{"type":"string","maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"province":{"type":"string","maxLength":200},"provinceCode":{"type":"string","maxLength":200},"zip":{"type":"string","maxLength":200},"countryCode":{"type":"string","allOf":[{"minLength":2},{"maxLength":2}]}},"required":["address1","countryCode"],"additionalProperties":false},"PadId":{"type":"string","pattern":"^pad_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A platform address: a pad-prefixed uuid"},"Geocode_1":{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"longitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"precision":{"$ref":"#/components/schemas/GeocodePrecision"}},"required":["latitude","longitude","precision"],"additionalProperties":false},"AddressVerification":{"type":"string","enum":["customer-confirmed","platform-verified","carrier-confirmed"],"description":"The strongest kind of source that vouches for the address, weakest first: `customer-confirmed` (customers confirmed it), `platform-verified` (a dataset or the validation provider matched it), `carrier-confirmed` (carriers delivered to it)."},"ConfidenceLevel":{"type":"string","enum":["unconfirmed","probable","verified"],"description":"How sure the registry is that the address exists and takes deliveries: `verified` (score 0.85 or above), `probable` (0.6 or above), `unconfirmed` (below)."},"AddressConfidence":{"type":"object","properties":{"score":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"level":{"$ref":"#/components/schemas/ConfidenceLevel"}},"required":["score","level"],"additionalProperties":false},"PlatformAddress":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PadId"},"countryCode":{"$ref":"#/components/schemas/CountryCode"},"unit":{"type":"string","maxLength":200},"streetNumber":{"type":"string","maxLength":200},"streetName":{"type":"string","maxLength":200},"streetType":{"type":"string","maxLength":200},"locality":{"type":"string","maxLength":200},"region":{"type":"string","maxLength":200},"postcode":{"type":"string","maxLength":200},"street":{"type":"string","maxLength":200},"lines":{"type":"array","items":{"type":"string","maxLength":200}},"buildingId":{"$ref":"#/components/schemas/PadId"},"geocode":{"$ref":"#/components/schemas/Geocode_1"},"verification":{"$ref":"#/components/schemas/AddressVerification"},"confidence":{"$ref":"#/components/schemas/AddressConfidence"}},"required":["id","countryCode","streetName","locality","postcode","street","lines","verification","confidence"],"additionalProperties":false},"PadId_1":{"type":"string","pattern":"^pad_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A platform address: a pad-prefixed uuid"},"Geocode_2":{"type":"object","properties":{"latitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"longitude":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"precision":{"$ref":"#/components/schemas/GeocodePrecision"}},"required":["latitude","longitude","precision"],"additionalProperties":false},"PlatformAddress_1":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PadId"},"countryCode":{"$ref":"#/components/schemas/CountryCode"},"unit":{"type":"string","maxLength":200},"streetNumber":{"type":"string","maxLength":200},"streetName":{"type":"string","maxLength":200},"streetType":{"type":"string","maxLength":200},"locality":{"type":"string","maxLength":200},"region":{"type":"string","maxLength":200},"postcode":{"type":"string","maxLength":200},"street":{"type":"string","maxLength":200},"lines":{"type":"array","items":{"type":"string","maxLength":200}},"buildingId":{"$ref":"#/components/schemas/PadId_1"},"geocode":{"$ref":"#/components/schemas/Geocode_2"},"verification":{"$ref":"#/components/schemas/AddressVerification"},"confidence":{"$ref":"#/components/schemas/AddressConfidence"}},"required":["id","countryCode","streetName","locality","postcode","street","lines","verification","confidence"],"additionalProperties":false},"AddressVerifiedEncoded":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/PlatformAddress"},"building":{"$ref":"#/components/schemas/PlatformAddress_1"}},"required":["address"],"additionalProperties":false},"AddressUnverifiedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AddressUnverified"]},"normalised":{"type":"array","items":{"type":"string","maxLength":200}},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/AddressCandidate"}}},"required":["_tag","normalised","candidates"],"additionalProperties":false},"PlatformAddressPageEncoded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PlatformAddress"}}},"required":["items"],"additionalProperties":false},"EvtId":{"type":"string","pattern":"^evt_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A evt-prefixed uuid, e.g. evt_9f8c1c2e-0000-4000-8000-000000000000"},"TxId":{"type":"string","pattern":"^tx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A tx-prefixed uuid, e.g. tx_9f8c1c2e-0000-4000-8000-000000000000"},"TenantId":{"type":"string","pattern":"^org_(test_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"An org-prefixed uuid, e.g. org_9f8c1c2e-0000-4000-8000-000000000000; a sandbox tenant is org_test_<uuid>"},"UsrId":{"type":"string","pattern":"^usr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A usr-prefixed uuid, e.g. usr_9f8c1c2e-0000-4000-8000-000000000000"},"AppId":{"type":"string","pattern":"^app_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A app-prefixed uuid, e.g. app_9f8c1c2e-0000-4000-8000-000000000000"},"InsId":{"type":"string","pattern":"^ins_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ins-prefixed uuid, e.g. ins_9f8c1c2e-0000-4000-8000-000000000000"},"CplId":{"type":"string","pattern":"^cpl_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cpl-prefixed uuid, e.g. cpl_9f8c1c2e-0000-4000-8000-000000000000"},"Actor":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["user"]},"id":{"$ref":"#/components/schemas/UsrId"},"impersonatedBy":{"type":"string","minLength":1},"viaPartner":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["system"]},"id":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["app"]},"id":{"$ref":"#/components/schemas/AppId"},"installationId":{"$ref":"#/components/schemas/InsId"}},"required":["_tag","id","installationId"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["customer"]},"id":{"$ref":"#/components/schemas/CplId"}},"required":["_tag","id"],"additionalProperties":false}]},"AddressEvidenceSource":{"type":"string","enum":["dataset","provider","carrier","customer"],"description":"Which kind of source vouched for an address: `dataset`, `provider`, `carrier` or `customer`."},"EvidenceMatch":{"type":"string","enum":["address","building"],"description":"What the source matched: the `address` itself, or only the unit's `building`."},"AddressEvidence":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/AddressEvidenceSource"},"name":{"type":"string","maxLength":200},"matched":{"$ref":"#/components/schemas/EvidenceMatch"},"checkedAt":{"type":"string"}},"required":["source","name","matched","checkedAt"],"additionalProperties":false},"addresses.address-registeredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["addresses.address-registered"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/PlatformAddress"},"key":{"type":"string","maxLength":200},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/AddressEvidence"}}},"required":["address","key","evidence"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"JournalHead":{"type":"object","properties":{"at":{"type":"string"},"sequence":{"type":"integer","minimum":0}},"required":["at"],"additionalProperties":false,"description":"Where a tenant's journal stood at a moment."}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A tenant JWT: sign in through the auth service, choose the organization, then `GET /api/auth/token`. Tokens last 15 minutes."}}},"security":[],"tags":[{"name":"addresses","description":"The platform's verified addresses: suggest while typing, verify and geocode, read by id."},{"name":"events","description":"The address registry's append-only event log, kept under the platform's own organization."}],"servers":[{"url":"https://addresses.getmanifold.io","description":"Production"}]}