Skip to content

Invite member

Endpoint

POST /organizations/{org_id}/users/invite

This endpoint sends an invitation email to a new user, prompting them to join your Tallyfy organization.

Request

Replace {org_id} with your Organization ID.

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient
  • Content-Type: application/json

Body (JSON)

The request body requires a JSON object containing the details of the user to invite.

Refer to the #definitions/inviteInput schema in Swagger. Key fields:

  • email (string, required): The email address of the person to invite.
  • first_name (string, optional): First name of the invitee.
  • last_name (string, optional): Last name of the invitee.
  • role (string, optional): The role to assign upon joining (e.g., standard, light, admin). Defaults may apply if omitted.
  • timezone (string, optional): Timezone for the new user (e.g., America/New_York).

Example Body:

{
  "email": "new.user@example.com",
  "first_name": "Charlie",
  "last_name": "Brown",
  "role": "standard"
}

Code samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/users/invite`;


const inviteData = {
  email: "charlie.brown@example.com",
  first_name: "Charlie",
  last_name: "Brown",
  role: "standard" // Valid roles: "standard", "light", "admin"
};


const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');
headers.append('Content-Type', 'application/json');


fetch(apiUrl, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(inviteData)
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error("Failed to invite member:", data);
            // Check for specific errors like 422 (user already exists)
            let errorMessage = `HTTP error! status: ${response.status}`;
            if (data && data.message) {
                 errorMessage += `, message: ${data.message}`;
            } else if (data) {
                 errorMessage += `, details: ${JSON.stringify(data)}`;
            }
            throw new Error(errorMessage);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log('Successfully invited member:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error inviting member:', error.message);
});

Response

A successful request returns a 200 OK or 201 Created status code. The response body typically contains the details of the invited user, often showing a pending or invited status until they accept.

{
  "data": {
    "id": 1005, // User ID assigned even before acceptance
    "email": "charlie.brown@example.com",
    "username": null, // Username set upon acceptance
    "first_name": "Charlie",
    "last_name": "Brown",
    "full_name": "Charlie Brown",
    "profile_pic": null,
    "active": false, // Not active until accepted
    "is_suspended": false,
    "created_at": "2024-05-21T10:00:00Z",
    "last_updated": "2024-05-21T10:00:00Z",
    "last_login_at": null,
    "activated_at": null, // Null until accepted
    "status": "invited", // Or similar status
    "user_role": "Standard"
    // ... other properties ...
  }
}

If the email address already belongs to an existing member of the organization, you will likely receive a 422 Unprocessable Entity error.

Members > Invite and activate members

Administrators can invite new members by sending email invitations which recipients must activate to gain account access while managing invites and member statuses through the organization settings.

Guests > Create guest

The POST endpoint creates guest users in an organization by accepting JSON data with required email and optional fields like name and company details while returning the newly created guest’s information upon success.

Code Samples > Managing members (Users)

The API enables organizations to manage their registered users through functionalities like inviting listing updating and removing members along with their roles and profiles.

Groups > Create group

A POST endpoint that creates organizational groups by accepting JSON data containing group name description members and guests while providing code samples in multiple programming languages and returning the newly created group details.
Get in touch
About Tallyfy