Record a physical presence
Record a physical presence in one jurisdiction. Recording a presence can establish nexus there, so the jurisdiction's exposure is recalculated. One record exists per organization, jurisdiction and category: a second create for the same three returns 200. A category the jurisdiction does not accept returns 400; get the accepted set from GET /physical-nexus/categories.
Authorization
Headers
Release date, as YYYY-MM-DD. Defaults to 2026-07-21.
Target organization id (Organization-Id selector).
Target connection id; resolves to its organization.
Platform entity id; resolves to a connection's organization.
Optional source to disambiguate an Entity-Id.
Body
ISO 3166-1 alpha-2 country of the jurisdiction.
State or province code within countryCode. FD for a federal jurisdiction.
Kind of physical presence to record. A category the jurisdiction does not accept returns 400; get the accepted set from GET /physical-nexus/categories.
PHYSICAL_BUSINESS_LOCATIONTELECOMMUTING_OR_REMOTE_EMPLOYEEWARRANTY_AND_REPAIR_SERVICESCATALOGUE_DISTRIBUTION_OR_ADVERTISING_MATERIALDELIVERY_BY_COMMON_CARRIERDELIVERY_BY_OWN_VEHICLESIN_STATE_SALES_PERSONINDEPENDENT_CONTRACTOR_OR_THIRD_PARTY_SALES_PERSONWAREHOUSE_AND_INVENTORY_PRESENCEEMPLOYEES_AGENTS_CONTRACTORSOWN_LEASE_A_PROPERTYINVENTORYDELIVERY_USING_COMPANY_VEHICLESOWN_BUSINESS_INFRASTRUCTURE_AND_EQUIPMENTON_SITE_INSTALLATION_MAINTENANCE_SERVICESFREQUENT_PARTICIPATION_IN_TRADE_SHOWS_EVENTSMANUFACTURE_OR_PRODUCTION_IN_CANADAPERFORMING_SERVICES_IN_THE_JURISDICTIONMANUFACTURING_FACILITIESSERVERS_DATA_CENTERSTRADE_SHOW_PRESENCETRADE_SHOW_PRESENCE_WITHOUT_SALESDIGITAL_INFRASTRUCTURE_LOCALIZEDPERMANENT_ESTABLISHMENTENTER_CONTRACTS_WITH_LOCALSCONSIGNMENT_STOCK_ARRANGEMENTSDate the physical presence began, as YYYY-MM-DD.
Date the physical presence ended, as YYYY-MM-DD. Omit it or send null while the presence is open-ended. Must not precede startDate.
Your identifier for this record in an external system.
Street address of the location.
Suite, unit, or other address detail.
City of the location.
ZIP or postal code of the location.
Response
Opaque unique identifier for this physical nexus.
Organization this physical nexus belongs to. Always present so a portfolio list that spans organizations stays unambiguous.
Display name of the owning organization. null if the name could not be loaded.
Whether the owning organization has any transactions. Editing a closed presence would move a date that nexus was already calculated against, so clients disable editing when this is true and endDate is set.
ISO 3166-1 alpha-2 country of the jurisdiction.
State or province code within countryCode. FD for a federal jurisdiction.
Kind of physical presence this record describes. Which categories a jurisdiction accepts varies; get the catalog from GET /physical-nexus/categories. Ignore unrecognized values.
PHYSICAL_BUSINESS_LOCATIONTELECOMMUTING_OR_REMOTE_EMPLOYEEWARRANTY_AND_REPAIR_SERVICESCATALOGUE_DISTRIBUTION_OR_ADVERTISING_MATERIALDELIVERY_BY_COMMON_CARRIERDELIVERY_BY_OWN_VEHICLESIN_STATE_SALES_PERSONINDEPENDENT_CONTRACTOR_OR_THIRD_PARTY_SALES_PERSONWAREHOUSE_AND_INVENTORY_PRESENCEEMPLOYEES_AGENTS_CONTRACTORSOWN_LEASE_A_PROPERTYINVENTORYDELIVERY_USING_COMPANY_VEHICLESOWN_BUSINESS_INFRASTRUCTURE_AND_EQUIPMENTON_SITE_INSTALLATION_MAINTENANCE_SERVICESFREQUENT_PARTICIPATION_IN_TRADE_SHOWS_EVENTSMANUFACTURE_OR_PRODUCTION_IN_CANADAPERFORMING_SERVICES_IN_THE_JURISDICTIONMANUFACTURING_FACILITIESSERVERS_DATA_CENTERSTRADE_SHOW_PRESENCETRADE_SHOW_PRESENCE_WITHOUT_SALESDIGITAL_INFRASTRUCTURE_LOCALIZEDPERMANENT_ESTABLISHMENTENTER_CONTRACTS_WITH_LOCALSCONSIGNMENT_STOCK_ARRANGEMENTSWhat created this record. USER for one you recorded through the API or the app; DEEL for one synced from the organization's Deel integration. Ignore unrecognized values.
USERDEELDate the physical presence began, as YYYY-MM-DD.
Date the physical presence ended, as YYYY-MM-DD. null while it is open-ended.
Your identifier for this record in an external system. null if it has none.
Street address of the location. Empty if the record does not carry it.
Suite, unit, or other address detail. Empty if the record does not carry it.
City of the location. Empty if the record does not carry it.
ZIP or postal code of the location. Empty if the record does not carry it.
When this record was created, as an RFC-3339 UTC timestamp.
When this record was last updated. null if it was never updated.
An existing physical presence matched. No new record was created.
Successful Response
The request was invalid.
Authentication failed or was missing.
The credential is not permitted for this request.
The requested resource was not found.
The request conflicts with existing state.
The request failed validation.