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. Read our business representatives guide to learn more.
To access this endpoint using an access token
you'll need to specify the /accounts/{accountID}/representatives.write scope.
POST
/accounts/{accountID}/representatives
curl -X POST "https://api.moov.io/accounts/{accountID}/representatives" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.04.00" \
-d '{
"name": {
"firstName": "Jordan",
"lastName": "Lee"
}
}'mc, _ := moov.NewClient()
var accountID string
mc.CreateRepresentative(ctx, accountID, moov.CreateRepresentative{
Address: &moov.Address{
AddressLine1: "12 Main Street",
City: "Cabot Cove",
StateOrProvince: "ME",
PostalCode: "04103",
Country: "US",
},
BirthDate: &moov.Date{
Day: 10,
Month: 11,
Year: 1985,
},
Email: "amanda@classbooker.dev",
GovernmentID: &moov.GovernmentID{
SSN: &moov.SSN{
Full: "111111111",
LastFour: "1111",
},
},
Name: moov.Name{
FirstName: "Amanda",
LastName: "Yang",
},
Phone: &moov.Phone{
Number: "8185551212",
CountryCode: "1",
},
Responsibilities: &moov.Responsibilities{
IsController: false,
IsOwner: true,
OwnershipPercentage: 38,
JobTitle: "CEO",
},
})
import { Moov } from "@moovio/sdk";
const moov = new Moov({
security: {
username: "",
password: "",
},
});
async function run() {
const result = await moov.representatives.create({
accountID: "5abfe3a5-7cd3-4f92-a8bd-19b64e3ccc10",
createRepresentative: {
name: {
firstName: "Jordan",
middleName: "Reese",
lastName: "Lee",
suffix: "Jr",
},
phone: {
number: "8185551212",
countryCode: "1",
},
email: "jordan.lee@classbooker.dev",
address: {
addressLine1: "123 Main Street",
addressLine2: "Apt 302",
city: "Boulder",
stateOrProvince: "CO",
postalCode: "80301",
country: "US",
},
birthDate: {
day: 9,
month: 11,
year: 1989,
},
responsibilities: {
ownershipPercentage: 38,
jobTitle: "CEO",
},
},
});
console.log(result);
}
run();declare(strict_types=1);
require 'vendor/autoload.php';
use Moov\MoovPhp;
use Moov\MoovPhp\Models\Components;
$sdk = MoovPhp\Moov::builder()
->setSecurity(
new Components\Security(
username: '',
password: '',
)
)
->build();
$createRepresentative = new Components\CreateRepresentative(
name: new Components\IndividualName(
firstName: 'Jordan',
middleName: 'Reese',
lastName: 'Lee',
suffix: 'Jr',
),
phone: new Components\PhoneNumber(
number: '8185551212',
countryCode: '1',
),
email: 'jordan.lee@classbooker.dev',
address: new Components\Address(
addressLine1: '123 Main Street',
addressLine2: 'Apt 302',
city: 'Boulder',
stateOrProvince: 'CO',
postalCode: '80301',
country: 'US',
),
birthDate: new Components\BirthDate(
day: 9,
month: 11,
year: 1989,
),
responsibilities: new Components\RepresentativeResponsibilities(
ownershipPercentage: 38,
jobTitle: 'CEO',
),
);
$response = $sdk->representatives->create(
accountID: '5abfe3a5-7cd3-4f92-a8bd-19b64e3ccc10',
createRepresentative: $createRepresentative
);
if ($response->representative !== null) {
// handle response
}package hello.world;
import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.errors.RepresentativeValidationError;
import io.moov.sdk.models.operations.CreateRepresentativeResponse;
import java.lang.Exception;
public class Application {
public static void main(String[] args) throws GenericError, RepresentativeValidationError, Exception {
Moov sdk = Moov.builder()
.security(Security.builder()
.username("")
.password("")
.build())
.build();
CreateRepresentativeResponse res = sdk.representatives().create()
.accountID("5abfe3a5-7cd3-4f92-a8bd-19b64e3ccc10")
.createRepresentative(CreateRepresentative.builder()
.name(IndividualName.builder()
.firstName("Jordan")
.lastName("Lee")
.middleName("Reese")
.suffix("Jr")
.build())
.phone(PhoneNumber.builder()
.number("8185551212")
.countryCode("1")
.build())
.email("jordan.lee@classbooker.dev")
.address(Address.builder()
.addressLine1("123 Main Street")
.city("Boulder")
.stateOrProvince("CO")
.postalCode("80301")
.country("US")
.addressLine2("Apt 302")
.build())
.birthDate(BirthDate.builder()
.day(9L)
.month(11L)
.year(1989L)
.build())
.responsibilities(RepresentativeResponsibilities.builder()
.ownershipPercentage(38L)
.jobTitle("CEO")
.build())
.build())
.call();
if (res.representative().isPresent()) {
System.out.println(res.representative().get());
}
}
}from moovio_sdk import Moov
from moovio_sdk.models import components
with Moov(
security=components.Security(
username="",
password="",
),
) as moov:
res = moov.representatives.create(account_id="5abfe3a5-7cd3-4f92-a8bd-19b64e3ccc10", name={
"first_name": "Jordan",
"middle_name": "Reese",
"last_name": "Lee",
"suffix": "Jr",
}, phone={
"number": "8185551212",
"country_code": "1",
}, email="jordan.lee@classbooker.dev", address={
"address_line1": "123 Main Street",
"address_line2": "Apt 302",
"city": "Boulder",
"state_or_province": "CO",
"postal_code": "80301",
"country": "US",
}, birth_date={
"day": 9,
"month": 11,
"year": 1989,
}, responsibilities={
"ownership_percentage": 38,
"job_title": "CEO",
})
# Handle response
print(res)require 'moov_ruby'
Models = ::Moov::Models
s = ::Moov::Client.new(
security: Models::Components::Security.new(
username: '',
password: ''
)
)
res = s.representatives.create(account_id: '5abfe3a5-7cd3-4f92-a8bd-19b64e3ccc10', create_representative: Models::Components::CreateRepresentative.new(
name: Models::Components::IndividualName.new(
first_name: 'Jordan',
middle_name: 'Reese',
last_name: 'Lee',
suffix: 'Jr'
),
phone: Models::Components::PhoneNumber.new(
number: '8185551212',
country_code: '1'
),
email: 'jordan.lee@classbooker.dev',
address: Models::Components::Address.new(
address_line1: '123 Main Street',
address_line2: 'Apt 302',
city: 'Boulder',
state_or_province: 'CO',
postal_code: '80301',
country: 'US'
),
birth_date: Models::Components::BirthDate.new(
day: 9,
month: 11,
year: 1989
),
responsibilities: Models::Components::RepresentativeResponsibilities.new(
ownership_percentage: 38,
job_title: 'CEO'
)
))
unless res.representative.nil?
# handle response
endusing Moov.Sdk;
using Moov.Sdk.Models.Components;
var sdk = new MoovClient(security: new Security() {
Username = "",
Password = "",
});
var res = await sdk.Representatives.CreateAsync(
accountID: "5abfe3a5-7cd3-4f92-a8bd-19b64e3ccc10",
body: new CreateRepresentative() {
Name = new IndividualName() {
FirstName = "Jordan",
MiddleName = "Reese",
LastName = "Lee",
Suffix = "Jr",
},
Phone = new PhoneNumber() {
Number = "8185551212",
CountryCode = "1",
},
Email = "jordan.lee@classbooker.dev",
Address = new Address() {
AddressLine1 = "123 Main Street",
AddressLine2 = "Apt 302",
City = "Boulder",
StateOrProvince = "CO",
PostalCode = "80301",
Country = "US",
},
BirthDate = new BirthDate() {
Day = 9,
Month = 11,
Year = 1989,
},
Responsibilities = new RepresentativeResponsibilities() {
OwnershipPercentage = 38,
JobTitle = "CEO",
},
}
);
// handle responseThe request completed successfully.
Describes a business representative.
{
"representativeID": "string",
"name": {
"firstName": "Jordan",
"middleName": "Reese",
"lastName": "Lee",
"suffix": "Jr"
},
"phone": {
"number": "8185551212",
"countryCode": "1"
},
"email": "jordan.lee@classbooker.dev",
"address": {
"addressLine1": "123 Main Street",
"addressLine2": "Apt 302",
"city": "Boulder",
"stateOrProvince": "CO",
"postalCode": "80301",
"country": "US"
},
"birthDateProvided": true,
"governmentIDProvided": true,
"responsibilities": {
"isController": true,
"isOwner": true,
"ownershipPercentage": 38,
"jobTitle": "CEO"
},
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z",
"disabledOn": "2019-08-24T14:15:22Z"
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The server could not understand the request due to invalid syntax.
{
"error": "string"
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request contained missing or expired authentication.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The user is not authorized to make the request.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The requested resource was not found.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request conflicted with the current state of the target resource.
{
"error": "string"
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.
{
"error": {
"name": {
"firstName": "string",
"middleName": "string",
"lastName": "string",
"suffix": "string"
},
"phone": {
"number": "string",
"countryCode": "string"
},
"email": "string",
"address": {
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"country": "string"
},
"birthDate": {
"day": "string",
"month": "string",
"year": "string"
},
"governmentID": {
"ssn": {
"full": "string",
"lastFour": "string"
},
"itin": {
"full": "string",
"lastFour": "string"
}
},
"responsibilities": {
"isController": "string",
"isOwner": "string",
"ownershipPercentage": "string",
"jobTitle": "string"
}
}
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
Request was refused due to rate limiting.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request failed due to an unexpected error.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request failed because a downstream service failed to respond.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
Headers
X-Moov-Version
string
Set this header to v2026.04.00 to use the API described in this specification. When omitted, the server defaults to v2024.01.00, which may not match the behavior documented here.
Possible values:
v2026.04.00
Path parameters
accountID
string
required
ID of the account.
Body
application/json
birthDate
object
Show child attributes
day
integer
required
month
integer
required
year
integer
required
governmentID
object
Show child attributes
itin
object
Show child attributes
full
string
Pattern
lastFour
string
ssn
object
Show child attributes
full
string
Pattern
lastFour
string
responsibilities
object
Describes the job responsibilities of a business representative.
Show child attributes
isController
boolean
Indicates whether this individual has significant management responsibilities within the business.
isOwner
boolean
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
Pattern
ownershipPercentage
integer
The percentage of ownership this individual has in the business (required if
isOwner is true).
address
object
Show child attributes
addressLine1
string
<=60 characters
required
Pattern
city
string
<=32 characters
required
Pattern
country
string
<=2 characters
required
postalCode
string
<=5 characters
required
stateOrProvince
string
<=2 characters
required
addressLine2
string
<=32 characters
Pattern
name
object
Show child attributes
firstName
string
<=64 characters
required
Pattern
The individual's first given name.
lastName
string
<=64 characters
required
Pattern
The individual's family name.
middleName
string
<=64 characters
Pattern
The individual's second given name, if any.
suffix
string
<=20 characters
Pattern
Suffix of a given name.
string<email>
<=255 characters
phone
object
Show child attributes
countryCode
string
<=1 characters
number
string
<=10 characters
Response
createdOn
string<date-time>
required
name
object
required
Show child attributes
firstName
string
<=64 characters
required
Pattern
The individual's first given name.
lastName
string
<=64 characters
required
Pattern
The individual's family name.
middleName
string
<=64 characters
Pattern
The individual's second given name, if any.
suffix
string
<=20 characters
Pattern
Suffix of a given name.
representativeID
string
required
Unique identifier for this representative.
updatedOn
string<date-time>
required
address
object
Show child attributes
addressLine1
string
<=60 characters
required
Pattern
city
string
<=32 characters
required
Pattern
country
string
<=2 characters
required
postalCode
string
<=5 characters
required
stateOrProvince
string
<=2 characters
required
addressLine2
string
<=32 characters
Pattern
birthDateProvided
boolean
Indicates whether this representative's birth date has been provided.
disabledOn
string<date-time>
string<email>
<=255 characters
governmentIDProvided
boolean
Indicates whether a government ID (SSN, ITIN, etc.) has been provided for this representative.
phone
object
Show child attributes
countryCode
string
<=1 characters
number
string
<=10 characters
responsibilities
object
Describes the job responsibilities of a business representative.
Show child attributes
isController
boolean
Indicates whether this individual has significant management responsibilities within the business.
isOwner
boolean
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
Pattern
ownershipPercentage
integer
The percentage of ownership this individual has in the business (required if
isOwner is true).