Create guest

Endpoint

POST /organizations/{org_id}/guests

Creates a new guest in your organization. If the email already exists as a guest globally, Tallyfy doesn’t create a duplicate. It adds that guest to your organization instead.

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)

Field	Type	Required	Description
email	string	Yes	Guest’s email address. Must pass RFC/DNS validation and can’t belong to an existing org member.
first_name	string	No	Max 200 characters.
last_name	string	No	Max 200 characters.
phone_1	string	No	Max 20 characters.
phone_2	string	No	Max 20 characters.
company_name	string	No	Max 200 characters.
company_url	string	No	Must be a valid URL.
contact_url	string	No	Must be a valid URL.
image_url	string	No	Must be a valid URL.
opportunity_url	string	No	Must be a valid URL.
opportunity_name	string	No	Max 200 characters.
timezone	string	No	E.g., America/Chicago.
status	string	No	Max 200 characters.
external_sync_source	string	No	Only salesforce is accepted.
external_date_creation	string	No	Format: Y-m-d H:i:s.

Minimal example:

{
  "email": "new.guest@contractor.com"
}

Fuller example:

{
  "email": "client.contact@acme.com",
  "first_name": "Client",
  "last_name": "Contact",
  "company_name": "ACME Corp",
  "phone_1": "+1-212-555-0123"
}

Code samples

Javascript

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

const guestData = {
  email: "external.partner@partnerco.com",
  first_name: "External",
  last_name: "Partner",
  company_name: "Partner Co"
};

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(guestData)
});

const data = await response.json();
if (!response.ok) {
  console.error('Failed:', response.status, data);
} else {
  console.log('Created guest:', JSON.stringify(data, null, 2));
}

Python

import requests
import json
import os

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/guests'

headers = {
    'Authorization': f'Bearer {access_token}',
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient',
    'Content-Type': 'application/json'
}

guest_payload = {
    'email': 'supplier.contact@supply.net',
    'first_name': 'Supplier',
    'company_name': 'Supply Network Inc.'
}

response = requests.post(api_url, headers=headers, json=guest_payload)
response.raise_for_status()

created_guest = response.json()
print('Created guest:')
print(json.dumps(created_guest, indent=4))

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateGuest {
    public static void main(String[] args) throws Exception {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String apiUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/guests";

        String jsonPayload = "{\"email\": \"contractor@domain.org\", \"first_name\": \"Contractor A\"}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 201) {
            System.out.println("Created guest: " + response.body());
        } else {
            System.err.println("Failed. Status: " + response.statusCode());
            System.err.println("Body: " + response.body());
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "os"
  "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
  if accessToken == "" { accessToken = "YOUR_PERSONAL_ACCESS_TOKEN" }
  orgId := os.Getenv("TALLYFY_ORG_ID")
  if orgId == "" { orgId = "YOUR_ORGANIZATION_ID" }
  apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/guests", orgId)

  guestData := map[string]interface{}{
    "email":        "client.rep@clientco.com",
    "first_name":   "Client",
    "last_name":    "Rep",
    "company_name": "Client Co Ltd",
  }

  jsonData, _ := json.Marshal(guestData)

  client := &http.Client{Timeout: 15 * time.Second}
  req, _ := http.NewRequest(http.MethodPost, apiUrl, bytes.NewBuffer(jsonData))
  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")
  req.Header.Set("Content-Type", "application/json")

  resp, err := client.Do(req)
  if err != nil {
    fmt.Printf("Request failed: %v\n", err)
    return
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)

  if resp.StatusCode != http.StatusCreated {
    fmt.Printf("Failed. Status: %d\nBody: %s\n", resp.StatusCode, string(body))
    return
  }

  fmt.Println("Created guest:")
  var prettyJSON bytes.Buffer
  if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
    fmt.Println(prettyJSON.String())
  } else {
    fmt.Println(string(body))
  }
}

C++

#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/json.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;

int main() {
    auto accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    auto orgId = U("YOUR_ORGANIZATION_ID");
    auto apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/guests");

    value payload = value::object();
    payload[U("email")] = value::string(U("cpp.guest@example.com"));
    payload[U("first_name")] = value::string(U("CPP"));
    payload[U("last_name")] = value::string(U("Guest"));
    payload[U("company_name")] = value::string(U("Example Systems"));

    http_client client(apiUrl);
    http_request request(methods::POST);
    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("Accept"), U("application/json"));
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));
    request.headers().set_content_type(U("application/json"));
    request.set_body(payload);

    auto response = client.request(request).get();
    auto body = response.extract_json().get();

    if (response.status_code() == status_codes::Created) {
        std::wcout << L"Created guest:\n" << body.serialize() << std::endl;
    } else {
        std::wcerr << L"Failed. Status: " << response.status_code()
                   << L"\nBody: " << body.serialize() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class CreateGuest
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task Main(string[] args)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/guests";

        var payload = new {
            email = "new.csharp.guest@example.com",
            first_name = "CSharp",
            company_name = "DotNet Co"
        };

        using var request = new HttpRequestMessage(HttpMethod.Post, apiUrl);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
        request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
        request.Headers.Add("X-Tallyfy-Client", "APIClient");
        request.Content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.SendAsync(request);
        var responseBody = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            using var doc = JsonDocument.Parse(responseBody);
            Console.WriteLine("Created guest:");
            Console.WriteLine(JsonSerializer.Serialize(doc.RootElement,
                new JsonSerializerOptions { WriteIndented = true }));
        }
        else
        {
            Console.WriteLine($"Failed. Status: {response.StatusCode}");
            Console.WriteLine($"Body: {responseBody}");
        }
    }
}

Response

A successful request returns a 201 Created status and a JSON object with the new guest’s data.

{
  "data": {
    "id": 4523,
    "email": "external.partner@partnerco.com",
    "last_accessed_at": null,
    "last_known_ip": null,
    "last_known_country": null,
    "first_name": "External",
    "last_name": "Partner",
    "created_at": "2025-01-15 10:30:00",
    "deleted_at": null,
    "link": "https://go.tallyfy.com/...",
    "details": {
      "status": null,
      "phone_1": null,
      "phone_2": null,
      "timezone": null,
      "image_url": null,
      "contact_url": null,
      "company_url": null,
      "opportunity_url": null,
      "company_name": "Partner Co",
      "opportunity_name": null,
      "external_sync_source": null,
      "external_date_creation": null,
      "cadence_days": null,
      "associated_members": null,
      "last_city": null,
      "last_country": null,
      "last_accessed_at": null,
      "disabled_at": null,
      "disabled_by": null,
      "reactivated_at": null,
      "reactivated_by": null
    }
  }
}

If the email belongs to an existing org member, you’ll get a 422 Unprocessable Entity error. If the email already exists as a guest globally, Tallyfy adds them to your organization rather than creating a duplicate.

---

Related articles

Code Samples > Managing guests

Tallyfy’s API lets you manage external guest users who participate in tasks without full…

Guests > Get guest

Retrieve a specific guest’s details by making a GET request to…

Guests > Update guest

Tallyfy’s PUT endpoint at /organizations/[org_id]/guests/[guest_email] updates the…

Members > Invite member

Invite new users to your Tallyfy organization by sending a POST request with their email, name…

Was this helpful?

YesNo