Get guest

Endpoint

GET /organizations/{org_id}/guests/{guest_email}

This endpoint retrieves the details for a specific guest user within the organization, identified by their email address.

Request

Replace {org_id} with your Organization ID and {guest_email} with the URL-encoded email address of the guest you want to retrieve (e.g., user%40example.com).

Headers

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

Query parameters (optional)

• with (string): Include additional related data, e.g., stats.

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const guestEmail = "guest.to.get@example.com";
const encodedEmail = encodeURIComponent(guestEmail); // Ensure email is URL encoded

const queryParams = '?with=stats'; // Example: Add query params if needed
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/guests/${encodedEmail}${queryParams}`;

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

fetch(apiUrl, {
    method: 'GET',
    headers: headers
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to get guest ${guestEmail}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully retrieved guest ${guestEmail}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error getting guest ${guestEmail}:`, error.message);
});

Python

import requests
import json
import os
from urllib.parse import quote

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
guest_email = "guest.to.get@example.com"
encoded_email = quote(guest_email) # URL-encode the email

api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/guests/{encoded_email}'

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

# Optional: Add query parameters
params = {
    'with': 'stats'
}

response = None
try:
    response = requests.get(api_url, headers=headers, params=params)
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    guest_data = response.json()
    print(f'Successfully retrieved guest {guest_email}:')
    print(json.dumps(guest_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred getting guest {guest_email}: {http_err}")
    if response is not None:
        print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed getting guest {guest_email}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON response for guest {guest_email}")
    if response is not None:
        print(f"Response Text: {response.text}")
except Exception as err:
     print(f"An unexpected error occurred: {err}")

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.stream.Collectors;

public class GetGuest {
    public static void main(String[] args) {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String guestEmail = "guest.to.get@example.com";
        String encodedEmail = URLEncoder.encode(guestEmail, StandardCharsets.UTF_8);

        String baseUrl = String.format("https://go.tallyfy.com/api/organizations/%s/guests/%s", orgId, encodedEmail);

        // Optional: Add query parameters
        Map<String, String> queryParamsMap = Map.of("with", "stats");
        String queryParamsString = queryParamsMap.entrySet().stream()
            .map(entry -> URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&", "?", ""));

        String apiUrl = baseUrl + (queryParamsMap.isEmpty() ? "" : queryParamsString);

        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")
                .GET()
                .build();

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

            // Swagger says 201, but 200 OK is more standard for GET
            if (response.statusCode() == 200 || response.statusCode() == 201) {
                System.out.println("Successfully retrieved guest " + guestEmail + ":");
                System.out.println(response.body());
                // TODO: Consider parsing JSON using Jackson/Gson
            } else {
                System.err.println("Failed to get guest " + guestEmail + ". Status: " + response.statusCode());
                System.err.println("Response Body: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        } catch (Exception e) {
             System.err.println("An unexpected error occurred: " + e.getMessage());
             e.printStackTrace();
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
  "net/url"
  "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" }
  email := "guest.to.get@example.com" // Email of the guest to retrieve

  // URL-encode the email for the path segment
  encodedEmail := url.PathEscape(email)

  baseUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/guests/%s", orgId, encodedEmail)

    // Optional: Add query parameters
    queryParams := url.Values{}
  queryParams.Set("with", "stats")

    apiUrl := baseUrl
    if len(queryParams) > 0 {
         apiUrl += "?" + queryParams.Encode()
    }

  client := &http.Client{Timeout: 10 * time.Second}
  req, err := http.NewRequest("GET", apiUrl, nil)
  if err != nil {
    fmt.Printf("Error creating get guest request for %s: %v\n", email, err)
    return
  }

  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")

  resp, err := client.Do(req)
  if err != nil {
    fmt.Printf("Error executing get guest request for %s: %v\n", email, err)
    return
  }
  defer resp.Body.Close()

  body, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    fmt.Printf("Error reading get guest response body for %s: %v\n", email, err)
    return
  }

    // Swagger says 201, but 200 OK is more standard for GET
  if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated {
    fmt.Printf("Failed to get guest %s. Status: %d\nBody: %s\n", email, resp.StatusCode, string(body))
    return
  }

  fmt.Printf("Successfully retrieved guest %s:\n", email)
    // Pretty print JSON response
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
  // TODO: Unmarshal JSON into a struct if needed
}

C++

#include <iostream>
#include <string>
#include <urlmon.h> // For UrlEscape (Windows example)
#include <windows.h>
#include <cpprest/http_client.h>
#include <cpprest/json.h>
#pragma comment(lib, "urlmon.lib")

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

// Basic URL encoding (Windows specific)
utility::string_t UrlEncodePathSegment(const utility::string_t& input) {
     DWORD size = 0;
     // Use URL_ESCAPE_SEGMENT_ONLY if available and appropriate,
     // otherwise URL_ESCAPE_PERCENT might be okay for email in path.
     UrlEscape(input.c_str(), nullptr, &size, URL_ESCAPE_PERCENT);
     if (size == 0) return input;
     std::vector<wchar_t> buffer(size);
     if (S_OK == UrlEscape(input.c_str(), buffer.data(), &size, URL_ESCAPE_PERCENT)) {
         return utility::string_t(buffer.data());
     } else { return input; }
}

pplx::task<void> GetTallyfyGuest(const utility::string_t& guestEmail)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    utility::string_t encodedEmail = UrlEncodePathSegment(guestEmail);

    uri_builder builder(U("https://go.tallyfy.com/api/organizations/"));
    builder.append_path(orgId);
    builder.append_path(U("guests"));
    builder.append_path(encodedEmail); // Append encoded email as path segment
    builder.append_query(U("with"), U("stats")); // Example query parameter
    utility::string_t apiUrl = builder.to_string();

    http_client client(apiUrl);
    http_request request(methods::GET);

    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"));

    return client.request(request).then([guestEmail](http_response response)
    {
        utility::string_t emailW = guestEmail;
        return response.extract_json().then([response, emailW](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                // Swagger says 201, check for 200 as well
                if (response.status_code() == status_codes::OK || response.status_code() == status_codes::Created) {
                    std::wcout << L"Successfully retrieved guest " << emailW << L":\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed to get guest " << emailW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during get guest: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during get guest response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        GetTallyfyGuest(U("guest.to.get@example.com")).wait();
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca). URL encoding uses Windows API.

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Text.Json;
using System.Web; // For HttpUtility

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

    public static async Task GetGuestAsync(string guestEmail)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";

        // URL encode the email for the path segment
        var encodedEmail = HttpUtility.UrlPathEncode(guestEmail);

        // Build URL with query parameters
        var query = HttpUtility.ParseQueryString(string.Empty);
        query["with"] = "stats"; // Example
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/guests/{encodedEmail}?{queryString}";

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Get, apiUrl);
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            request.Headers.Add("X-Tallyfy-Client", "APIClient");

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

            // Swagger says 201, check for 200 as well
            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine($"Successfully retrieved guest {guestEmail}:");
                // Pretty print JSON
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                } catch (JsonException) {
                    Console.WriteLine(responseBody);
                }
            }
            else
            {
                Console.WriteLine($"Failed to get guest {guestEmail}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception getting guest {guestEmail}: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     await GetGuestAsync("guest.to.get@example.com");
    // }
}

Response

A successful request returns a 200 OK or 201 Created status code and a JSON object containing a data field with the guest’s details.

{
  "data": {
    "id": "guest_code_abc123",
    "email": "guest.to.get@example.com",
    "last_accessed_at": "2024-05-15T10:00:00Z",
    "details": {
      "first_name": "Specific",
      "last_name": "Guest",
      "status": "active",
      "company_name": "Guest Company",
      // ... other guest details ...
    },
    // Included if requested with 'with=stats'
    "stats": { ... }
  }
}

If the guest email is not found or you lack permission, you will likely receive a 404 Not Found or 403 Forbidden error.

---

Related articles

Guests > List guests

The GET endpoint retrieves guest users from an organization with their details like email access history location information and optional statistics using various programming languages through authenticated API requests.

Guests > Delete guest

A DELETE endpoint that removes guest users from an organization by their email address and returns either a success status code or guest record details upon completion.

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.

Guests > Update guest

The PUT endpoint allows modification of existing guest user details through their email address with updated information like name phone and company details while maintaining the original email address.