Team Management

Invite team members to your business, assign roles, and manage access. Each business has its own team with role-based permissions controlling who can create invoices, approve them, and manage settings.

Endpoints

Method	Endpoint	Description
POST	`/v1/team/invite`	Invite a team member
GET	`/v1/team`	List team members
POST	`/v1/team/invitations/{token}/accept`	Accept an invitation
DELETE	`/v1/team/invitations/{id}`	Revoke an invitation
PATCH	`/v1/team/members/{id}/role`	Update a member's role
DELETE	`/v1/team/members/{id}`	Remove a team member

🔑
All endpoints on this page require authentication. See Authentication for details.

Roles

Each team member has a role that controls what they can do within the business. Roles are hierarchical — higher roles inherit all permissions of lower roles.

Role	Permissions
`OWNER`	Full access. Manage billing, delete the business, and transfer ownership. One owner per business
`ADMIN`	Manage team members, approve/reject invoices, update business settings and FIRS configuration
`MANAGER`	View all invoices, manage customers and products, submit invoices to FIRS
`CREATOR`	Create and edit draft invoices, manage customers and products
`VIEWER`	Read-only access to invoices, customers, and products

⚠️
Only OWNER and ADMIN roles can invite team members, update roles, and approve or reject invoices. The OWNER role cannot be assigned via the API — it is set when the business is created.

Invite a Team Member

Send an email invitation to join your business. The invitee receives a link with a unique token to accept the invitation.

curl -X POST https://e-invoicing.earnipay.com/v1/team/invite \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_xyz789",
    "email": "[email protected]",
    "role": "CREATOR"
  }'

Parameter	Type	Required	Description
`businessId`	string	Yes	ID of the business to invite the member to
`email`	string	Yes	Email address of the person to invite
`role`	string	Yes	One of: `ADMIN`, `MANAGER`, `CREATOR`, `VIEWER`

{
  "statusCode": 201,
  "message": "Invitation sent successfully.",
  "data": {
    "id": "inv_team_abc123",
    "businessId": "biz_xyz789",
    "email": "[email protected]",
    "role": "CREATOR",
    "status": "PENDING",
    "expiresAt": "2026-03-20T14:00:00.000Z",
    "createdAt": "2026-03-13T14:00:00.000Z"
  }
}

The invitee receives an email with a link containing the invitation token. If they already have an Earnipay account, they can accept directly. If not, they need to sign up first.

List Team Members

Retrieve all team members and pending invitations for a business.

curl "https://e-invoicing.earnipay.com/v1/team?businessId=biz_xyz789" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Type	Required	Description
`businessId`	string	Yes	Filter by business ID

{
  "statusCode": 200,
  "message": "Team members retrieved successfully.",
  "data": {
    "members": [
      {
        "id": "mem_owner01",
        "userId": "usr_abc123",
        "email": "[email protected]",
        "firstName": "Ada",
        "lastName": "Okafor",
        "role": "OWNER",
        "joinedAt": "2026-03-13T10:00:00.000Z"
      },
      {
        "id": "mem_admin01",
        "userId": "usr_def456",
        "email": "[email protected]",
        "firstName": "Emeka",
        "lastName": "Ibe",
        "role": "ADMIN",
        "joinedAt": "2026-03-14T09:00:00.000Z"
      }
    ],
    "invitations": [
      {
        "id": "inv_team_abc123",
        "email": "[email protected]",
        "role": "CREATOR",
        "status": "PENDING",
        "expiresAt": "2026-03-20T14:00:00.000Z",
        "createdAt": "2026-03-13T14:00:00.000Z"
      }
    ]
  }
}

The response separates active members (who have accepted) from pending invitations (who haven't yet).

Accept an Invitation

Accept a team invitation using the token from the invitation email. The accepting user must be authenticated.

curl -X POST https://e-invoicing.earnipay.com/v1/team/invitations/eyJhbGciOiJIUzI1NiIs.../accept \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Type	Location	Description
`token`	string	Path	Invitation token from the email link

{
  "statusCode": 200,
  "message": "Invitation accepted successfully.",
  "data": {
    "id": "mem_create01",
    "userId": "usr_ghi789",
    "businessId": "biz_xyz789",
    "email": "[email protected]",
    "role": "CREATOR",
    "joinedAt": "2026-03-14T11:30:00.000Z"
  }
}

{
  "statusCode": 400,
  "message": "This invitation has expired. Please ask the business admin to send a new one.",
  "error": "Bad Request"
}

Revoke an Invitation

Cancel a pending invitation before it's accepted. Only OWNER and ADMIN roles can revoke invitations.

curl -X DELETE https://e-invoicing.earnipay.com/v1/team/invitations/inv_team_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Type	Location	Description
`id`	string	Path	Invitation ID (from the invite or list response)

{
  "statusCode": 200,
  "message": "Invitation revoked successfully."
}

Update a Member's Role

Change a team member's role. Only OWNER and ADMIN roles can update member roles. Admins cannot change the owner's role or promote others to owner.

curl -X PATCH https://e-invoicing.earnipay.com/v1/team/members/mem_create01/role \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "role": "MANAGER"
  }'

Parameter	Type	Required	Description
`role`	string	Yes	New role: `ADMIN`, `MANAGER`, `CREATOR`, or `VIEWER`

{
  "statusCode": 200,
  "message": "Member role updated successfully.",
  "data": {
    "id": "mem_create01",
    "userId": "usr_ghi789",
    "email": "[email protected]",
    "role": "MANAGER",
    "updatedAt": "2026-03-15T10:00:00.000Z"
  }
}

Remove a Team Member

Remove a member from the business. The removed member loses all access immediately. Only OWNER and ADMIN roles can remove members. The business owner cannot be removed.

curl -X DELETE https://e-invoicing.earnipay.com/v1/team/members/mem_create01 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Type	Location	Description
`id`	string	Path	Member ID (from the list response)

{
  "statusCode": 200,
  "message": "Team member removed successfully."
}

⚠️
Removing a member is immediate and permanent. The member loses access to all business data including invoices, customers, and products. Any invoices they created remain in the system.

Error Handling

Status Code	Error	Description
`400`	Bad Request	Invalid parameters, expired invitation token, or invalid role
`401`	Unauthorized	Missing or expired access token
`403`	Forbidden	Insufficient role (only OWNER/ADMIN can manage team)
`404`	Not Found	Member ID or invitation ID doesn't exist
`409`	Conflict	User is already a member, or invitation already sent to this email

{
  "statusCode": 409,
  "message": "An invitation has already been sent to [email protected] for this business.",
  "error": "Conflict"
}

{
  "statusCode": 403,
  "message": "The business owner's role cannot be changed.",
  "error": "Forbidden"
}