--- title: "Create an address for a firm" url: "https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8/operations/createFirmAddressV2" --- > Full API specification: https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8.md # Create an address for a firm `POST` `/v2/firms/{firmId}/addresses` Operation ID: `createFirmAddressV2` Creates a new address and associates it with the specified firm under the authenticated customer's scope. Returns 404 if the firm does not exist or is not visible to the authenticated customer. A 403 is returned only when the caller's token lacks the required scope; cross-customer access returns 404, not 403. Returns 400 when the request body fails validation (V2 error shape). ## Path parameters - `firmId` (string, uuid, required) - ID of the firm ## Header parameters - `Idempotency-Key` (string, uuid, optional) - Client-generated UUID used to deduplicate retried requests. When provided, the server caches the first successful response for this key and returns it for any subsequent request with the same key from the same client, without re-processing. ## Request body (required) Content types: `application/json` ## Responses - `201` - Address created successfully. - `400` - One or more request fields failed validation - `401` - No valid bearer token was presented - `403` - The token does not carry the required scope - `404` - The requested resource does not exist or is not visible to the caller - `429` - Rate limit exceeded. The caller has exceeded the maximum number of requests allowed per rate-limit window for the authenticated credential. NOTE: The response body for this status deviates from the standard V2 error shape ({message, details, code}). The body contains only a top-level "message" string. Clients should treat the Retry-After header as the authoritative retry signal and must not parse the message string. - `500` - An unexpected server error occurred ## OpenAPI definition ```yaml openapi: 3.0.1 info: title: Identity API version: v1.275.8 servers: - url: https://api.sandbox.agentsync.io/id description: Sandbox server - url: https://api.agentsync.io/id description: Production server paths: /v2/firms/{firmId}/addresses: post: summary: Create an address for a firm description: > Creates a new address and associates it with the specified firm under the authenticated customer's scope. Returns 404 if the firm does not exist or is not visible to the authenticated customer. A 403 is returned only when the caller's token lacks the required scope; cross-customer access returns 404, not 403. Returns 400 when the request body fails validation (V2 error shape). operationId: createFirmAddressV2 tags: - Addresses security: - oauth2: - identity.profiles.write parameters: - $ref: "#/components/parameters/FirmIdParam" - $ref: "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateAddressRequest" responses: "201": description: Address created successfully. headers: ratelimit-limit: $ref: "#/components/headers/ratelimit-limit" ratelimit-remaining: $ref: "#/components/headers/ratelimit-remaining" ratelimit-reset: $ref: "#/components/headers/ratelimit-reset" content: application/json: schema: $ref: "#/components/schemas/AddressV2" "400": $ref: "#/components/responses/V2BadRequest" "401": $ref: "#/components/responses/V2Unauthorized" "403": $ref: "#/components/responses/V2Forbidden" "404": $ref: "#/components/responses/V2NotFound" "429": $ref: "#/components/responses/V2TooManyRequests" "500": $ref: "#/components/responses/V2InternalServerError" security: - oauth2: - identity.profiles.write components: parameters: FirmIdParam: name: firmId in: path description: ID of the firm required: true schema: type: string format: uuid IdempotencyKeyParam: name: Idempotency-Key in: header required: false schema: type: string format: uuid description: > Client-generated UUID used to deduplicate retried requests. When provided, the server caches the first successful response for this key and returns it for any subsequent request with the same key from the same client, without re-processing. schemas: CreateAddressRequest: title: CreateAddressRequest type: object required: - type - addressLine1 - city - state - zip - country properties: type: $ref: "#/components/schemas/AddressType" addressLine1: type: string description: First line of the street address. example: 123 Main St addressLine2: type: string nullable: true description: Second line of the street address (suite, unit, etc.). example: Apt 4B city: type: string description: City. example: Denver state: type: string minLength: 2 maxLength: 2 description: Two-letter US state code. example: CO zip: type: string pattern: ^\d{5}(-\d{4})?$ description: ZIP code in 5-digit or ZIP+4 format. example: "80202" county: type: string nullable: true description: County name. example: Denver country: type: string minLength: 2 maxLength: 2 description: Country code (ISO alpha-2). example: US moveInDate: type: string format: date nullable: true description: Date the person moved to this address (YYYY-MM-DD). example: 2020-01-15 preferred: type: boolean default: false description: > Whether this should be the person's preferred address. When the person has no existing addresses, the server sets this to true regardless of the supplied value. example: false AddressV2: title: AddressV2 type: object required: - id - type - addressLine1 - city - state - zip - country - preferred - createdAt properties: id: type: string format: uuid description: Address identifier. readOnly: true example: 550e8400-e29b-41d4-a716-446655440000 type: $ref: "#/components/schemas/AddressType" addressLine1: type: string description: First line of the street address. example: 123 Main St addressLine2: type: string nullable: true description: Second line of the street address (suite, unit, etc.). example: Apt 4B city: type: string description: City. example: Denver state: type: string minLength: 2 maxLength: 2 description: Two-letter US state code. example: CO zip: type: string nullable: true pattern: ^\d{5}(-\d{4})?$ description: ZIP code in 5-digit or ZIP+4 format. example: "80202" county: type: string nullable: true description: County name. example: Denver country: type: string nullable: true minLength: 2 maxLength: 2 description: Country code (ISO alpha-2). example: US moveInDate: type: string format: date nullable: true description: Date the person moved to this address (YYYY-MM-DD). example: 2020-01-15 preferred: type: boolean description: Whether this is the person's preferred address. example: true createdAt: type: string format: date-time description: RFC3339 UTC timestamp when the address was created. readOnly: true example: 2024-01-15T10:30:00Z updatedAt: type: string format: date-time nullable: true description: RFC3339 UTC timestamp when the address was last updated. readOnly: true example: 2024-01-15T14:45:00Z AddressType: type: string enum: - MAILING - BUSINESS - PHYSICAL description: Type of address V2Error: type: object required: - message - details - code properties: message: type: string description: Human-readable error summary. Do not parse — use "code" for branching. example: Validation failed details: type: array description: Per-field validation errors. Empty for all non-400 responses. items: $ref: "#/components/schemas/V2FieldError" code: type: string description: Stable machine-readable error code. enum: - validation_failed - unauthorized - unauthorized_scope - resource_not_found - conflict - unprocessable - unsupported_media_type - rate_limited - internal example: validation_failed V2FieldError: type: object required: - param - message properties: param: type: string description: The request field that failed validation example: email message: type: string description: Human-readable description of the failure example: must not be blank headers: ratelimit-limit: description: > Maximum number of requests allowed per rate-limit window for the authenticated credential. The value returned in this header is authoritative; do not cache it. schema: type: integer ratelimit-remaining: description: Number of requests remaining in the current rate-limit window. schema: type: integer ratelimit-reset: description: > Unix timestamp (seconds) after which at least one additional request slot becomes available. In a sliding window this is a hint, not a hard reset point — retrying exactly at this instant may still return 429 under sustained load. schema: type: integer Retry-After: description: > Minimum seconds to wait before retrying. Use this value directly as your retry delay; it already accounts for any server-side backoff. schema: type: integer responses: V2BadRequest: description: One or more request fields failed validation content: application/json: schema: $ref: "#/components/schemas/V2Error" example: message: Validation failed code: validation_failed details: - param: email message: must not be blank V2Unauthorized: description: No valid bearer token was presented content: application/json: schema: $ref: "#/components/schemas/V2Error" example: message: Authentication required code: unauthorized details: [] V2Forbidden: description: The token does not carry the required scope content: application/json: schema: $ref: "#/components/schemas/V2Error" example: message: Insufficient scope code: unauthorized_scope details: [] V2NotFound: description: The requested resource does not exist or is not visible to the caller content: application/json: schema: $ref: "#/components/schemas/V2Error" example: message: Resource not found code: resource_not_found details: [] V2TooManyRequests: description: > Rate limit exceeded. The caller has exceeded the maximum number of requests allowed per rate-limit window for the authenticated credential. NOTE: The response body for this status deviates from the standard V2 error shape ({message, details, code}). The body contains only a top-level "message" string. Clients should treat the Retry-After header as the authoritative retry signal and must not parse the message string. headers: ratelimit-limit: $ref: "#/components/headers/ratelimit-limit" ratelimit-remaining: $ref: "#/components/headers/ratelimit-remaining" ratelimit-reset: $ref: "#/components/headers/ratelimit-reset" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: type: object required: - message properties: message: type: string example: message: API rate limit exceeded V2InternalServerError: description: An unexpected server error occurred content: application/json: schema: $ref: "#/components/schemas/V2Error" example: message: An unexpected error occurred code: internal details: [] securitySchemes: oauth2: type: oauth2 description: > OAuth2 client credentials. The `tokenUrl` below is the SANDBOX token endpoint; for production use `https://auth.agentsync.io/oauth2/token`. OpenAPI 3.0 permits only one token URL per flow, so both cannot be expressed here — see the Authentication section for the full environment table. flows: clientCredentials: tokenUrl: https://auth.sandbox.agentsync.io/oauth2/token scopes: identity.profiles.read: Read access to producer profile resources (V2 customer-facing) identity.profiles.write: Write access to producer profile resources (V2 customer-facing) ```