/ Guides / People / Create people

Create people

Add new or existing people to an account.

How it works

The following diagram describes the different steps required to create a person with Equals Money. Click on the image to enlarge it.

Diagram showing steps involved in creating a person

Create a person

Post/v2/people

Request

Use this request to grant someone access to an account.

If they don't have a personId, this request will create both a new personId and a personaId. If they already have a personId, this request will create a new personaId for them.

Sample requestRequest structure
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/people' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "F12345",
    "firstName": "Alison",
    "lastName": "Abraham",
    "roleName": "Viewer",
    "dob": "1996-07-17",
    "emailAddress": "a.abraham@acme.com"
    "primaryMobileNumber": "+447798121212",
    "status": "active",
    "employeeNumber": "948",
    "jobTitle": "Administrative Assistant",
    "notifyEmailTrans": true,
    "createdByPersonaId": "288cf796-c1ad-4ffd-9eb9-af210bff0ea0"
  }'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/people' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "string",
    "firstName": "string",
    "lastName": "string",
    "roleName": "string",
    "dob": "string",
    "emailAddress": "string",
    "primaryMobileNumber": "string",
    "status": "string",
    "employeeNumber": "string",
    "jobTitle": "string",
    "notifyEmailTrans": boolean,
    "createdByPersonaId": "string"
}

Request body schema

Parameter Description
accountId
string
required		 The ID of the account that you're adding a person to.

Allowable values:
An existing accountId (<= 36 characters)
firstName
string
required		 The person's first name.

Allowable values:
<= 256 characters
lastName
string
required		 The person's last name.

Allowable values:
<= 256 characters
roleName
string
required		 The person's role. Learn more about role types.

Allowable values:
Owner,Admin, Payer, Viewer, Accountant, User
dob
string or null		 The person's date of birth.

Allowable values:
A valid string
emailAddress
string
required		 The person's email address. This will be used to identify them and cannot be changed later. If a person with this email address already exists, this request will add the existing person to the account. If you're using approved email domains, then we'll check whether the email domain is on your list of approved email domains and will return an error if not.

Allowable values:
<= 256 characters
primaryMobileNumber
string or null		 The person's primary mobile phone number.

Allowable values:
<= 50 characters
status
string		 The status to give the person.

Allowable values:
active, deactivated
employeeNumber
string		 The person's employee number.

Allowable values:
<= 256 characters
jobTitle
string or null		 The person's job title.

Allowable values:
<= 256 characters
notifyEmailTrans
boolean		 Whether or not the person has chosen to receive email notifications. By default, this is set to false.

Allowable values:
true, false
createdByPersonaId
string (uuid)		 Your persona ID.

Allowable values:
<= 36 characters
addToUserPool
boolean		 Whether or not to create a new user in the Cognito user pool. By default, this is set to true.

Allowable values:
true, false
sendInvite
boolean		 Whether or not to send a Cognito invitation to the person so that they can complete the sign-up process. By default, this is set to true.

Allowable values:
true, false
emailTheme
string		 The theme used in emails that are sent to this person.

Allowable values:
em-light, em-dark

Response

If your request is successful, you'll receive a 201 response containing an id.

Sample responseResponse structure
Copy
Copied
{
  "avatar": {
    "url": "",
    "fileName": ""
  },
  "id": "ef6d922f-70d5-4433-835c-8c77fa40d814",
  "productId": "d926625b-5e11-4ec1-b4cd-0af2a8021efc",
  "sub": "2a5a39cf-fda0-4901-9372-3f9039a2ee94",
  "firstName": "Alison",
  "lastName": "Abraham",
  "title": null,
  "middleInitials": null,
  "dob": "1996-07-17",
  "gender": null,
  "nationality": null,
  "countryOfResidence": null,
  "status": "active",
  "primaryMobileNumber": "+447798121212",
  "primaryEmailAddress": "a.abraham@acme.com",
  "createdAt": "2024-01-02T13:47:01.000Z",
  "updatedAt": "2024-01-02T13:47:02.000Z",
  "emailTheme": "em-light",
  "persona": {
    "id": "32684fcd-b4be-438a-88d2-ee9b5f3eecd3",
    "emailAddress": "a.abraham@acme.com",
    "employeeNumber": "948",
    "workNumber": null,
    "status": "invited",
    "jobTitle": "Administrative Assistant",
    "createdByPersonaId": null,
    "transactionalEmailPreference": true,
    "cardTransactionPushNotificationPreference": false,
    "createdAt": "2024-01-02T13:47:02.000Z",
    "updatedAt": "2024-01-02T13:47:02.000Z",
    "inviteSentDate": "2024-01-02T13:47:02.000Z"
  }
}
Copy
Copied
{
  "avatar": {
    "url": "string",
    "fileName": "string"
  },
  "id": "string",
  "productId": "string",
  "sub": "string",
  "firstName": "string",
  "lastName": "string",
  "title": "string",
  "middleInitials": "string",
  "dob": "string",
  "gender": "string",
  "nationality": "string",
  "countryOfResidence": "string",
  "status": "string",
  "primaryMobileNumber": "string",
  "primaryEmailAddress": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "emailTheme": "string",
  "persona": {
    "id": "string",
    "emailAddress": "string",
    "employeeNumber": "string",
    "workNumber": "string",
    "status": "string",
    "jobTitle": "string",
    "createdByPersonaId": "string",
    "transactionalEmailPreference": boolean,
    "cardTransactionPushNotificationPreference": boolean,
    "createdAt": "string",
    "updatedAt": "string",
    "inviteSentDate": "string"
  }
}

For more detailed information about this request and its response, see the API reference.