An authorized user is an individual a business customer authorizes to act on its behalf. A business can link as many authorized users as it needs, giving each one the access or signing authority their role calls for. Unlike beneficial owners (who are captured at onboarding and read-only), you add and manage authorized users on their own once the business customer exists.

Common use cases

• Give an officer the ability to sign agreements on behalf of the business (authorized signatory).
• Grant an employee portal access with a specific role.
• Record a person who is both an owner and an active user of the business's account.
• Add a non-US user who has an ITIN instead of an SSN.
• Keep an authorized user's contact details current as the team changes.

Scenarios

Each scenario adds an authorized user to an existing business customer. The person's role decides which details you send: a signatory needs contact details for sign-off, a portal user needs a role, and so on. A new authorized user is ACTIVE as soon as it's created.

Before you begin (all scenarios)

• The business customer exists, and you have its id or externalId.
• You have the person's name and mobile number, and at least one mailing address.
• You've decided whether this person should have portal access, and with what role.

Scenario 1: Add an authorized signatory

Add a person who can sign agreements and act on the business's account, for example an officer who accepts the account agreement. Set actAsAuthorizedSignatory to true, and provide their email and mobile number so they can be reached for sign-off.

You'll also need: the signatory's email and a reachable mobile number.

Request

POST /v1/customer/id/4015210/authorizedUser

{
  "externalId": "auth-signatory-001",
  "firstName": "Albert",
  "lastName": "Sangma",
  "mobilePhone": "534-539-5743",
  "email": "[email protected]",
  "actAsAuthorizedSignatory": true,
  "mailingAddress": [
    {
      "addressLine1": "addrew134",
      "addressLine2": "Street lane",
      "city": "Tempe",
      "state": "AZ",
      "zip": "48395",
      "isPrimary": true
    }
  ],
  "portalAccess": {
    "grantAccess": false
  }
}

Scenario 2: Grant a team member portal access

Add an employee who needs to sign in to the portal, and assign the role that grants their permissions. Set grantAccess to true and pass the role for that person.

You'll also need: the role identifier configured for your program.

Request

POST /v1/customer/id/4015210/authorizedUser

{
  "externalId": "auth-portal-002",
  "firstName": "Maria",
  "lastName": "Lopez",
  "mobilePhone": "602-555-0134",
  "email": "[email protected]",
  "mailingAddress": [
    {
      "addressLine1": "100 Market St",
      "city": "San Jose",
      "state": "CA",
      "zip": "95113",
      "isPrimary": true
    }
  ],
  "portalAccess": {
    "grantAccess": true,
    "role": 4
  }
}

Scenario 3: Add an owner who also acts on the account

Some people both own the business and act on its account. Add them as an authorized user and set isBeneficialOwner to true so the record reflects that they're an owner as well.

You'll also need: confirmation that this person is a beneficial owner of the business.

Request

POST /v1/customer/id/4015210/authorizedUser

{
  "externalId": "auth-owner-003",
  "firstName": "Sumesh",
  "lastName": "P",
  "mobilePhone": "870-743-3432",
  "email": "[email protected]",
  "isBeneficialOwner": true,
  "actAsAuthorizedSignatory": true,
  "mailingAddress": [
    {
      "addressLine1": "2683",
      "addressLine2": "MyStreet",
      "city": "Gary",
      "state": "AZ",
      "zip": "46014",
      "isPrimary": true
    }
  ],
  "portalAccess": {
    "grantAccess": false
  }
}

Scenario 4: Add a user who has an ITIN, not an SSN

For a person without a US Social Security Number, provide their Taxpayer Identification (ITIN) instead. Use taxIdentification in place of ssn.

You'll also need: the person's ITIN in XXX-XX-XXXX format.

Request

POST /v1/customer/id/4015210/authorizedUser

{
  "externalId": "auth-itin-004",
  "firstName": "Jhon",
  "lastName": "Doe",
  "mobilePhone": "534-539-5743",
  "isUSCitizen": false,
  "taxIdentification": {
    "type": "ITIN",
    "id": "936-92-2093"
  },
  "mailingAddress": [
    {
      "addressLine1": "addrew134",
      "city": "Tempe",
      "state": "AZ",
      "zip": "48395",
      "isPrimary": true
    }
  ],
  "portalAccess": {
    "grantAccess": false
  }
}

Response (all scenarios): 201 Created

Create returns 201 Created with the new authorized user's ID in the url (Location) response header, and no body.

HTTP/1.1 201 Created
url: /v1/customer/id/4015210/authorizedUser/id/7481

Store the returned id and your externalId to retrieve or update the user later.

Keep a user current

When a person's details change, update the authorized user in place. Make a POST request to /v1/customer/id/{customerId}/authorizedUser/id/{authorizedUserId} with only the fields you're changing.

Request

POST /v1/customer/id/4052981/authorizedUser/id/7481

{
  "mobilePhone": "602-555-0199"
}

Response: 204 No Content

You can update most details (name, mobile number, date of birth, tax identification, mailing address, portal access). Two fields are fixed once set: email cannot be changed, and an externalId, once assigned, cannot be updated.

Retrieve and list users

• Get one user: GET /v1/customer/id/{customerId}/authorizedUser/id/{authorizedUserId} returns the full record, including isBeneficialOwner, actAsAuthorizedSignatory, portalAccess, and verification.
• List a business's users: GET /v1/customer/id/{customerId}/authorizedUser returns every authorized user linked to that customer.
• Search across your program: POST /v1/authorizedUser/list filters, sorts, and pages through authorized users, for example everyone created after a given date.

Search request

POST /v1/authorizedUser/list

{
  "pageNumber": 1,
  "pageSize": 25,
  "sortOptions": {
    "sortBy": "lastUpdatedOn",
    "sortOrder": "desc"
  },
  "criteria": {
    "filters": [
      {
        "operator": "eq",
        "key": "entity.customer.id",
        "values": ["4015210"]
      }
    ]
  }
}

You can filter on id, externalId, entity.customer.id, entity.customer.externalId, status, createdOn, createdBy, lastUpdatedOn, and lastUpdatedBy, and sort by id, createdOn, or lastUpdatedOn.

Request reference

The complete set of fields for the create request. Scenarios above use subsets of these. Send the request to /v1/customer/id/{customerId}/authorizedUser (or the externalId variant).

Core fields

portalAccess

mailingAddress[]

At least one mailing address must be provided, and only one address can be marked primary.

taxIdentification

Statuses

A new authorized user is ACTIVE by default as soon as it's created. Each user is screened for identity and sanctions; read the outcome from the verification object (ofacStatus and cipStatus) when you retrieve the user.

Validation

The prerequisites above are the validations, and PCE enforces them when you submit. If a check fails, the request returns an error and no authorized user is created.

• firstName, lastName, mobilePhone, and portalAccess are present.
• At least one mailing address is provided, with no more than one marked primary.
• For a user without an SSN, a valid taxIdentification (ITIN) is provided.

Best practices

Next steps

See also

• Beneficial Owners & Authorized Users: how owners and authorized users relate
• Accounts: the business customer these users are linked to
• Getting Started: authentication, webhooks, idempotency, and shared setup