Skip to main content

​
Overview

Invitations allow you to add members to your organization. When you create an invitation, the recipient receives an email with a link to accept. Invitations expire after 7 days.

​
Prerequisites

  • An organization ID
  • A valid API key with permission to manage organization members

​
Code Example

import { Factify } from "@factify/sdk";

const factify = new Factify({ bearerAuth: process.env.FACTIFY_KEY });

async function inviteMember(organizationId: string, email: string) {
  const result = await factify.organizations.invites.create({
    organizationId,
    body: {
      email,
      message: "Welcome to the team!" // Optional custom message
    }
  });

  console.log(`Invitation sent: ${result.invite?.id}`);
  return result.invite;
}

inviteMember(
  "org_01h2xcejqtf2nbrexx3vqjhp41",
  "pam.beesly@dundermifflin.com"
);

​
Response

{
  "invite": {
    "id": "inv_01h2xcejqtf2nbrexx3vqjhp42",
    "organization_id": "org_01h2xcejqtf2nbrexx3vqjhp41",
    "email": "pam.beesly@dundermifflin.com",
    "status": "ORGANIZATION_INVITE_STATUS_PENDING",
    "sender": {
      "id": "user_01h2xcejqtf2nbrexx3vqjhp40",
      "type": "USER_TYPE_USER_ACCOUNT",
      "name": "John Doe"
    },
    "created_at": "2024-01-15T09:30:00Z",
    "expires_at": "2024-01-22T09:30:00Z",
    "message": "Welcome to the team!"
  }
}

​
Options

ParameterTypeDescription
organizationIdstringRequired. The organization to invite to
emailstringRequired. Email address of the recipient
messagestringOptional. Custom message (max 2000 bytes)
idempotencyKeystringOptional. Client-provided key for safe retries

​
Idempotency

If you include an idempotency_key, duplicate requests within 24 hours return the original response without resending the email. This is useful for retry logic. 
const result = await factify.organizations.invites.create({
  organizationId: "org_01h2xcejqtf2nbrexx3vqjhp41",
  body: {
    email: "pam.beesly@dundermifflin.com",
    idempotencyKey: "my-unique-request-id-123"
  }
});

​
Listing Invitations

Check pending invitations for your organization: 
const invites = await factify.organizations.invites.list({
  organizationId: "org_01h2xcejqtf2nbrexx3vqjhp41",
  status: ["ORGANIZATION_INVITE_STATUS_PENDING"]
});

for await (const page of invites) {
  console.log(page.items);
}

​
Revoking an Invitation

Cancel a pending invitation: 
await factify.organizations.invites.revoke({
  organizationId: "org_01h2xcejqtf2nbrexx3vqjhp41",
  inviteId: "inv_01h2xcejqtf2nbrexx3vqjhp42"
});

​
Error Handling

ErrorCauseSolution
FAILED_PRECONDITIONEmail belongs to existing memberUser is already in the organization
PERMISSION_DENIEDInsufficient permissionsEnsure your account can manage organization members
NOT_FOUNDInvalid organization IDVerify the organization exists

​
Next Steps

Authentication

Learn about API key management

Organizations

Manage organization settings