Ask Moov Beta
Generative AI is experimental and can make mistakes.
Guides Use cases
SDKs & UIs
API Changelog
  1. API reference
  2. Moov accounts
  3. Business representatives

Add a representative

Moov accounts associated with businesses require information regarding individuals who represent the business. You can provide this information by creating a representative. Each account is allowed a maximum of 7 representatives.

To use this endpoint from the browser, you’ll need to specify the /accounts/{accountID}/representatives.write scope when generating a token.
POST
/accounts/{accountID}/representatives
cURL JavaScript 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

curl -X POST "https://api.moov.io/accounts/{accountID}/representatives" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "name": {
      "firstName": "Amanda",
      "lastName": "Yang"
    },
    "address": {
      "addressLine1": "12 Main Street",
      "city": "Cabot Cove",
      "stateOrProvince": "ME",
      "postalCode": "04103",
      "country": "US"
    },
    "birthDate": {
      "day": 10,
      "month": 11,
      "year": 1985
    },
    "email": "amanda@classbooker.dev",
    "governmentID": {
      "ssn": {
        "full":"111111111",
        "lastFour":"1111"
      }
    },
    "responsibilities": {
      "isController": false,
      "isOwner": true,
      "ownershipPercentage": 38,
      "jobTitle": "CEO"
    }
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

const moov = new Moov(credentialsObject);

const accountID = "accountID";
const representativePayload = {
  name: {
    firstName: "Amanda",
    lastName: "Yang"
  },
  address: {
    addressLine1: "12 Main Street",
    city: "Cabot Cove",
    stateOrProvince: "ME",
    postalCode: "04103",
    country: "US"
  },
  birthDate: {
    day: 10,
    month: 11,
    year: 1985
  },
  email: "amanda@classbooker.dev",
  governmentID: {
    ssn: {
      full: "111111111",
      lastFour: "1111"
    }
  },
  responsibilities: {
    isController: false,
    isOwner: true,
    ownershipPercentage: 38,
    jobTitle: "CEO"
  }
};

const account = await moov.representatives.create(accountID, representativePayload);
200 404 422 429
Representative created.
Describes a business representative.
{
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 302",
    "city": "Boulder",
    "country": "US",
    "postalCode": "80301",
    "stateOrProvince": "CO"
  },
  "birthDateProvided": false,
  "createdOn": "2019-08-24T14:15:22Z",
  "disabledOn": "2019-08-24T14:15:22Z",
  "email": "amanda@classbooker.dev",
  "governmentIDProvided": false,
  "name": {
    "firstName": "Amanda",
    "lastName": "Yang",
    "middleName": "Amanda",
    "suffix": "Jr"
  },
  "phone": {
    "countryCode": "1",
    "number": "8185551212"
  },
  "representativeID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "responsibilities": {
    "isController": false,
    "isOwner": true,
    "jobTitle": "CEO",
    "ownershipPercentage": 38
  },
  "updatedOn": "2019-08-24T14:15:22Z"
}
The specified account or representative was not found.
The request body could not be processed.
Request was refused due to rate limiting.

Response headers

X-Retry-In

string <duration>
How long (in milliseconds) to wait until able to retry the request.

Path parameters

accountID

string <uuid> required
ID of the account.

Body

application/json
Describes the fields available when creating a representative.

address

object
Residential address for an individual. Business addresses not accepted.
right_key Show child attributes

addressLine1

string <=60 characters required

addressLine2

string <=32 characters

city

string <=24 characters required

country

string <=2 characters required

postalCode

string <=5 characters required

stateOrProvince

string <=2 characters required

birthDate

object
An individual’s birthdate.
right_key Show child attributes

day

integer required

month

integer required

year

integer required

email

string<email> <=255 characters Pattern
Email address.

governmentID

object
right_key Show child attributes

itin

object
right_key Show child attributes

full

string <=64 characters

lastFour

string <=4 characters

ssn

object
right_key Show child attributes

full

string <=64 characters

lastFour

string <=4 characters

name

object
An individual’s name.
right_key Show child attributes

firstName

string <=64 characters required Pattern
Name this person was given. This is usually the the same as first name.

lastName

string <=64 characters required Pattern
Family name of this person. This is usually the the same as last name.

middleName

string <=64 characters Pattern
Name this person was given. This is usually the the same as first name.

suffix

string <=20 characters Pattern
Suffix of a given name.

phone

object
right_key Show child attributes

countryCode

string <=1 characters

number

string<phone> <=10 characters

responsibilities

object
Describes the job responsibilities of an individual.
right_key Show child attributes

isController

boolean required
Indicates whether this individual has significant management responsibilities within the business.

isOwner

boolean required
If true, this field indicates that the individual has a business ownership stake of at least 25% in the business. If the representative does not own at least 25% of the business, this field should be false.

jobTitle

string <=64 characters required

ownershipPercentage

integer required
The percentage of ownership this individual has in the business (required if isOwner is true).

Response

application/json
Describes a business representative.

address

object
right_key Show child attributes

addressLine1

string <=60 characters required

addressLine2

string <=32 characters

city

string <=24 characters required

country

string <=2 characters required

postalCode

string <=5 characters required

stateOrProvince

string <=2 characters required

birthDateProvided

boolean
Indicates whether this representative’s birth date has been provided.

createdOn

string<date-time> <=24 characters

disabledOn

string

email

string<email> <=255 characters Pattern
Email address.

governmentIDProvided

boolean
Indicates whether a government ID (SSN, ITIN, etc.) has been provided for this representative.

name

object
An individual’s name.
right_key Show child attributes

firstName

string <=64 characters required Pattern
Name this person was given. This is usually the the same as first name.

lastName

string <=64 characters required Pattern
Family name of this person. This is usually the the same as last name.

middleName

string <=64 characters Pattern
Name this person was given. This is usually the the same as first name.

suffix

string <=20 characters Pattern
Suffix of a given name.

phone

object
right_key Show child attributes

countryCode

string <=1 characters

number

string<phone> <=10 characters

representativeID

string<uuid> <=36 characters Pattern
UUID v4

responsibilities

object
Describes the job responsibilities of an individual.
right_key Show child attributes

isController

boolean required
Indicates whether this individual has significant management responsibilities within the business.

isOwner

boolean required
If true, this field indicates that the individual has a business ownership stake of at least 25% in the business. If the representative does not own at least 25% of the business, this field should be false.

jobTitle

string <=64 characters required

ownershipPercentage

integer required
The percentage of ownership this individual has in the business (required if isOwner is true).

updatedOn

string<date-time> <=24 characters