Pleaxy

Raise purchase orders, approve and pay invoices, and set up your workspace.

API reference

Org profiles

Your company's business profile and billing details.

More about this resource

A buyer or supplier organization's business profile - billing details and primary contact.

Endpoints

Get org profile

Returns your company profile.

GET/v1/workspaces/{regionId}/profile

Returns

200 OK with the object shown in the response.

More details

Returns the caller's organization profile for this workspace (buyer or supplier, based on the caller's role).

Response fields

  • billingAddressstring

    The billing address on one line, derived from billingAddressParts. On a profile saved before addresses had separate fields, the text as it was typed, and billingAddressParts is absent.

  • billingAddressPartsobject

    The billing address as separate fields (see UpdateOrgProfile).

  • billingAddressNeedsReviewboolean

    true when an older one-line address couldn't be split into fields with confidence and an administrator should check it. Cleared by saving the address.

  • billingAddressLegacyTextstring

    The one-line address as it was before it was split into fields, kept unchanged.

  • listedInDirectoryboolean

    Supplier profiles only: the supplier chose to be found by buyers searching Pleaxy (see UpdateOrgProfile). Absent means not listed.

  • directoryIdstring

    Supplier profiles only: the opaque id buyers invite a listed supplier by, set the first time it is listed and kept if it is switched off and on again. Buyers never see your contact email through the directory.

Errors

  • 404 Not Found - No org profile exists yet for this workspace and role.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/profile
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/profile" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "id": "string",
   "role": "buyer" | "supplier",
   "regionId": "string",
   "regionName": "string",
   "companyName": "string",
   "billingEmail": "string",
   "billingAddress": "string",
   "billingAddressParts": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
   },
   "billingAddressNeedsReview": boolean,
   "billingAddressLegacyText": "string",
   "taxId": "string",
   "currency": "string",
   "countries": [ "string" ],
   "timeZone": "string",
   "primaryContactName": "string",
   "primaryContactEmail": "string",
   "listedInDirectory": boolean,
   "directoryId": "string",
   "createdAt": "string"
}

Update org profile

Updates your company profile.

PATCH/v1/workspaces/{regionId}/profile

Body

  • regionNamestring

    The region's display name, up to 40 characters.

  • currencystring

    ISO 4217 code, case-insensitive (stored uppercase). A buyer workspace's currency can't change once it has any purchase order (drafts aside) or invoice.

  • companyNamestring

    Legal or display company name.

  • billingEmailstring

    Email address invoices/receipts are sent to.

  • billingAddressPartsobject | null

    The billing address as separate fields: line1 (required, up to 200 characters), line2, city, region (state, province or county), postalCode, and country (required, ISO 3166-1 alpha-2). Which other fields are required depends on the country: city everywhere except city-states such as SG and HK; region in US, CA, MX, BR and AU; postalCode in most of Europe and in US, CA, MX, BR, AU, IN and JP, and optional elsewhere, including most of Latin America. billingAddress is derived from it. Saving any address clears billingAddressNeedsReview. null clears the address.

  • billingAddressstring

    The billing address as one line of text, up to 500 characters. Ignored when billingAddressParts is sent; otherwise it replaces the address and its separate fields.

  • taxIdstring

    Tax identification number, up to 64 characters. Printed with the billing address on the invoice PDFs Pleaxy creates for invoices between connected companies.

  • primaryContactNamestring

    Primary contact's name.

  • primaryContactEmailstring

    Primary contact's email.

  • countriesstring[]

    Replaces the region's countries, as ISO 3166-1 alpha-2 codes, unique, up to 250. Never changes currency.

  • geographyPresetIdstring | null

    Records which preset (for example eu, uk, apac, global) the country list came from; null clears it.

  • timeZonestring

    IANA time zone, e.g. Europe/London. Sets the workspace's "today" for payment dates.

  • listedInDirectoryboolean

    Supplier profiles only (ignored for a buyer): true lists you in the supplier directory every buyer on Pleaxy searches when inviting a supplier, by company name and region only - never your contact email. A buyer can then invite you without knowing your email; the invite goes to your account's contact. false takes you out of the directory.

Returns

200 OK with the object shown in the response.

More details

Updates one or more fields of the caller's organization profile.

Errors

  • 400 Bad Request - A field failed validation - for example regionName is longer than 40 characters, currency isn't an ISO 4217 code, or billingAddressParts is missing a part its country requires (such as region and postalCode for a US address).
  • 409 Conflict - currency differs from the stored one, and this buyer workspace already has purchase orders or invoices recorded in it. Nothing is changed. To buy in another currency, add a region.
  • 404 Not Found - No org profile exists yet for this workspace and role.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
PATCH /v1/workspaces/{regionId}/profile
Request
curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/profile" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "regionName": "string",
   "currency": "string",
   "companyName": "string",
   "billingEmail": "string",
   "billingAddressParts": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
   },
   "taxId": "string",
   "primaryContactName": "string",
   "primaryContactEmail": "string",
   "countries": [ "string" ],
   "geographyPresetId": "string",
   "timeZone": "string",
   "listedInDirectory": boolean
}
Response · 200 OK
{
   "id": "string",
   "role": "buyer" | "supplier",
   "regionId": "string",
   "regionName": "string",
   "companyName": "string",
   "billingEmail": "string",
   "billingAddress": "string",
   "billingAddressParts": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
   },
   "billingAddressNeedsReview": boolean,
   "billingAddressLegacyText": "string",
   "taxId": "string",
   "currency": "string",
   "countries": [ "string" ],
   "timeZone": "string",
   "primaryContactName": "string",
   "primaryContactEmail": "string",
   "listedInDirectory": boolean,
   "directoryId": "string",
   "createdAt": "string"
}
Talk to us