# Guests

Guests are where all of the data lives. With these requests, you're able to search for guests and create new guests within Stampede. This is great if your app collects data and you would like to send it to Stampede. 

## Fetch/search guests

<mark style="color:blue;">`GET`</mark> `/v1/guests`

#### Query Parameters

| Name   | Type   | Description |
| ------ | ------ | ----------- |
| search | String |             |
| limit  | Date   |             |
| cursor | String |             |

{% tabs %}
{% tab title="200: OK " %}

```typescript
{
    data: {
        id: string;
        organization_id: string;
        profile_id: number;
        last_interacted_at: string;
        created_at: string;
        data_opt_in_at: string;
        sms_opt_in_at: string;
        email_opt_in_at: string;
        user_profile: {
            email: string;
            first: string;
            id: number;
            phone: string;
            last: string;
        };
        organization_profile_tags: {
            id: string;
            organization_registration_id: string;
            tag_id: string;
        }[];
    }[];
    links: {
        first: string | null;
        last: string | null;
        next: string | null;
        prev: string | null;
    };
}

```

{% endtab %}
{% endtabs %}

## Fetch a single guest with it's ID

<mark style="color:blue;">`GET`</mark> `/v1/guests/:guest_id`

#### Query Parameters

| Name                                        | Type   | Description         |
| ------------------------------------------- | ------ | ------------------- |
| guest\_id<mark style="color:red;">\*</mark> | String | The ID of the guest |

{% tabs %}
{% tab title="200: OK " %}

```typescript
{
    id: string;
    organization_id: string;
    profile_id: number;
    last_interacted_at: string;
    created_at: string;
    data_opt_in_at: string | null;
    sms_opt_in_at: string | null;
    email_opt_in_at: string;
    user_profile: {
        email: string;
        id: number;
        verified: number;
        first: string | null;
        last: string | null;
        phone: string | null;
        lat: number | null;
        lng: number | null;
        birth_day: number | null;
        birth_month: number | null;
        postcode: string | null;
        country: string | null;
        gender: string | null;
    };
    organization_registration_personalisation_choice: any[];
    custom_question_answers: any[];
}

```

{% endtab %}
{% endtabs %}

## Create a new guest

<mark style="color:green;">`POST`</mark> `/v1/guests`

#### Request Body

| Name                                                      | Type              | Description                                               |
| --------------------------------------------------------- | ----------------- | --------------------------------------------------------- |
| email<mark style="color:red;">\*</mark>                   | String            | The guest email address. It must be a valid email format. |
| first                                                     | String            | The first name of the guest                               |
| last                                                      | String            | The last name of the guest                                |
| privacy.data<mark style="color:red;">\*</mark>            | Boolean           | Is the user opted into giving out there data              |
| privacy.marketing.email<mark style="color:red;">\*</mark> | Boolean           | Is the user opted in to email marketing                   |
| privacy.marketing.sms<mark style="color:red;">\*</mark>   | string            | Is the user opted in to sms marketing                     |
| gender                                                    | "m" \| "f" \| "o" | The gender of a guest                                     |
| phone                                                     | E.164             | The phone number of the guest                             |

{% tabs %}
{% tab title="200: OK " %}

```typescript
{
  id: string;
  organization_id: string;
  profile_id: number;
  last_interacted_at: string;
  created_at: string;
  data_opt_in_at: string;
  sms_opt_in_at: string;
  email_opt_in_at: string;
  user_profile: {
    first: string | null;
    last: string | null;
    email: string;
    id: number;
  };
};
```

{% endtab %}

{% tab title="400: Bad Request " %}

```typescript
{
  stack: string;
  code: number;
  message: string[];
  url: string;
  method: string;
}
```

{% endtab %}

{% tab title="409: Conflict " %}

```typescript
{
  stack: string;
  code: number;
  message: string;
  url: string;
  method: string;
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.stampede.ai/guests/guests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.