REST API reference

SignUpGenius API

15 endpoints for SignUpGenius. Each one is a POST with a JSON body, called with your API key.

Base URL
https://cotlet.dev/api/v1/signupgenius
Connects with
Your own SignUpGenius organizer account
Integration page
SignUpGenius
SignUpGenius Endpoints
Endpoint Access Description
list_signups read Sign-ups you created, with title, group, dates and how many slots are filled.
get_signup read One sign-up with its description, link and every slot: title, date, time, location, wanted and filled.
list_participants read Who signed up for which slot, with name, email, quantity and answers to custom questions.
list_groups read Your groups (the people you invite) with member counts.
list_group_members read Members of a group with name and email.
create_signup write New sign-up saved as a draft. Nothing is visible or sent until you publish it.
add_slots write Add slots (roles or tasks) to a sign-up, on one or more dates and times.
update_slot write Change a slot's title, quantity, location or help comment. Quantity cannot go below the people already signed up.
duplicate_signup write Copy a sign-up with a new title. The copy is an unpublished draft.
publish_signup write Make a draft sign-up live and return its public link. Does not send invites.
add_participant write Sign someone up for a slot as the organizer, from a group or as a new person.
move_participant write Move a participant from their slot to another open slot on the same sign-up.
remove_participant write Delete a participant from a slot.
send_message write Email the people on a sign-up: everyone, those who signed up, or those who have not.
add_group_member write Add a person to one of your groups so you can invite them later. Sends nothing.

List sign-ups

read

POST https://cotlet.dev/api/v1/signupgenius/list_signups

Returns your sign-ups, newest first, with the group each one is assigned to and the count of filled and wanted spots. Use signup_id from each item in the other endpoints. Drafts are included only when status is drafts.

Parameters

Parameters: list_signups
NameTypeDescription
status enum active, past or drafts. Default: active.
limit integer 1 to 100. Default: 25.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/list_signups \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("signupgenius", "list_signups")
Node.js
const result = await cotlet.call('signupgenius', 'list_signups');
CLI
cotlet call signupgenius list_signups

Example response

{
  "signups": [
    {
      "signup_id": "50463821",
      "title": "Spring bake sale",
      "status": "active",
      "group": "PTA",
      "filled": 9,
      "wanted": 12,
      "next_date": "2027-05-09"
    },
    {
      "signup_id": "50471160",
      "title": "Book fair volunteers",
      "status": "active",
      "group": "PTA",
      "filled": 4,
      "wanted": 8,
      "next_date": "2027-03-12"
    }
  ],
  "next_cursor": null
}

Get sign-up

read

POST https://cotlet.dev/api/v1/signupgenius/get_signup

Returns the sign-up and its slots in date order. Each slot has the ID other endpoints need and the number of people wanted and filled. Set open_only to get only slots that still have spots.

Parameters

Parameters: get_signup
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
open_only boolean Only slots that still have spots.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/get_signup \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2"}'
Python
result = client.call("signupgenius", "get_signup", {"signup_id":"signup_8c41d2"})
Node.js
const result = await cotlet.call('signupgenius', 'get_signup', {"signup_id":"signup_8c41d2"});
CLI
cotlet call signupgenius get_signup --data '{"signup_id":"signup_8c41d2"}'

Example response

{
  "signup_id": "50463821",
  "title": "Spring bake sale",
  "status": "active",
  "url": "https://www.signupgenius.com/go/50463821",
  "slots": [
    {
      "slot_id": "3381902441",
      "title": "Bake sale shift",
      "start": "2027-05-09T09:00:00-04:00",
      "location": "School lobby",
      "wanted": 4,
      "filled": 4
    },
    {
      "slot_id": "3381902442",
      "title": "Bake sale shift",
      "start": "2027-05-09T11:00:00-04:00",
      "location": "School lobby",
      "wanted": 4,
      "filled": 2
    }
  ]
}

List participants

read

POST https://cotlet.dev/api/v1/signupgenius/list_participants

Returns one row per participant, in slot order. Email is empty when the person did not give one. Answers to custom questions come as question and answer pairs. Use from and to to limit the slot dates.

Parameters

Parameters: list_participants
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
from date Only slots on or after this date.
to date Only slots on or before this date.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/list_participants \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2"}'
Python
result = client.call("signupgenius", "list_participants", {"signup_id":"signup_8c41d2"})
Node.js
const result = await cotlet.call('signupgenius', 'list_participants', {"signup_id":"signup_8c41d2"});
CLI
cotlet call signupgenius list_participants --data '{"signup_id":"signup_8c41d2"}'

Example response

{
  "signup_id": "50463821",
  "participants": [
    {
      "participant_id": "771204518",
      "first_name": "Jordan",
      "last_name": "Reyes",
      "email": "jordan@example.com",
      "slot_id": "3381902441",
      "quantity": 1,
      "answers": [
        {
          "question": "Dietary notes",
          "answer": "Nut free"
        }
      ]
    },
    {
      "participant_id": "771204533",
      "first_name": "Sam",
      "last_name": "Ortiz",
      "email": null,
      "slot_id": "3381902442",
      "quantity": 2,
      "answers": []
    }
  ]
}

List groups

read

POST https://cotlet.dev/api/v1/signupgenius/list_groups

Returns every group in your account with its ID and member count. Use group_id from each item in create_signup, list_group_members and add_group_member.

Parameters

No parameters.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/list_groups \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("signupgenius", "list_groups")
Node.js
const result = await cotlet.call('signupgenius', 'list_groups');
CLI
cotlet call signupgenius list_groups

Example response

{
  "groups": [
    {
      "group_id": "9120334",
      "name": "PTA",
      "members": 86
    },
    {
      "group_id": "9120571",
      "name": "Class 3B",
      "members": 24
    }
  ]
}

List group members

read

POST https://cotlet.dev/api/v1/signupgenius/list_group_members

Returns the people in one group, with name and email, so your agent can compare them with a sign-up. Members without an email have it empty.

Parameters

Parameters: list_group_members
NameTypeDescription
group_id required string Group ID from list_groups.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/list_group_members \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group_8c41d2"}'
Python
result = client.call("signupgenius", "list_group_members", {"group_id":"group_8c41d2"})
Node.js
const result = await cotlet.call('signupgenius', 'list_group_members', {"group_id":"group_8c41d2"});
CLI
cotlet call signupgenius list_group_members --data '{"group_id":"group_8c41d2"}'

Example response

{
  "group_id": "9120571",
  "members": [
    {
      "member_id": "6610021",
      "first_name": "Maya",
      "last_name": "Chen",
      "email": "maya@example.com"
    },
    {
      "member_id": "6610022",
      "first_name": "Leo",
      "last_name": "Park",
      "email": "leo@example.com"
    }
  ]
}

Create sign-up

write

POST https://cotlet.dev/api/v1/signupgenius/create_signup

Creates an empty sign-up as a draft and returns its ID. Nobody can see it and no email goes out until publish_signup. It reaches no one and you can delete the draft, so it runs without asking first. Add slots next with add_slots.

Parameters

Parameters: create_signup
NameTypeDescription
title required string Sign-up title.
description string Text shown at the top of the sign-up.
group_id string Group to assign, from list_groups.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/create_signup \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"title"}'
Python
result = client.call("signupgenius", "create_signup", {"title":"title"})
Node.js
const result = await cotlet.call('signupgenius', 'create_signup', {"title":"title"});
CLI
cotlet call signupgenius create_signup --data '{"title":"title"}'

Example response

{
  "signup_id": "50463821",
  "title": "Spring bake sale",
  "status": "draft",
  "group_id": "9120334"
}

Add slots

write

POST https://cotlet.dev/api/v1/signupgenius/add_slots

Adds one slot per date-time you pass, all with the same title and quantity, and returns each new slot ID. The sign-up keeps its status, so slots added to a draft stay hidden. It reaches no one, so it runs without asking first.

Parameters

Parameters: add_slots
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
title required string Slot name, e.g. "Main dish" or "Setup crew".
quantity required integer Number of people wanted per date.
dates string[] ISO date-times the slot applies to, with time zone. Empty: slot without a date.
location string Where the slot takes place.
help_comment string Short note that explains the slot.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/add_slots \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"50463821","title":"Bake sale shift","quantity":4,"dates":["2027-05-09T09:00:00-04:00","2027-05-09T11:00:00-04:00","2027-05-09T13:00:00-04:00"],"location":"School lobby","help_comment":"Bring a float of small bills."}'
Python
result = client.call("signupgenius", "add_slots", {"signup_id":"50463821","title":"Bake sale shift","quantity":4,"dates":["2027-05-09T09:00:00-04:00","2027-05-09T11:00:00-04:00","2027-05-09T13:00:00-04:00"],"location":"School lobby","help_comment":"Bring a float of small bills."})
Node.js
const result = await cotlet.call('signupgenius', 'add_slots', {"signup_id":"50463821","title":"Bake sale shift","quantity":4,"dates":["2027-05-09T09:00:00-04:00","2027-05-09T11:00:00-04:00","2027-05-09T13:00:00-04:00"],"location":"School lobby","help_comment":"Bring a float of small bills."});
CLI
cotlet call signupgenius add_slots --data '{"signup_id":"50463821","title":"Bake sale shift","quantity":4,"dates":["2027-05-09T09:00:00-04:00","2027-05-09T11:00:00-04:00","2027-05-09T13:00:00-04:00"],"location":"School lobby","help_comment":"Bring a float of small bills."}'

Example response

{
  "signup_id": "50463821",
  "status": "draft",
  "slots_added": 3,
  "slots": [
    {
      "slot_id": "3381902441",
      "start": "2027-05-09T09:00:00-04:00",
      "title": "Bake sale shift",
      "wanted": 4,
      "filled": 0
    },
    {
      "slot_id": "3381902442",
      "start": "2027-05-09T11:00:00-04:00",
      "title": "Bake sale shift",
      "wanted": 4,
      "filled": 0
    },
    {
      "slot_id": "3381902443",
      "start": "2027-05-09T13:00:00-04:00",
      "title": "Bake sale shift",
      "wanted": 4,
      "filled": 0
    }
  ]
}

Update slot

write

POST https://cotlet.dev/api/v1/signupgenius/update_slot

Changes the fields you pass and returns the slot as it is now. A quantity lower than the people already signed up is refused. On a published sign-up the change is visible at once, but no one is told, so it runs without asking first.

Parameters

Parameters: update_slot
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
slot_id required string Slot ID from get_signup.
fields required object Any of title, quantity, location, help_comment.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/update_slot \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","fields":"fields"}'
Python
result = client.call("signupgenius", "update_slot", {"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","fields":"fields"})
Node.js
const result = await cotlet.call('signupgenius', 'update_slot', {"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","fields":"fields"});
CLI
cotlet call signupgenius update_slot --data '{"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","fields":"fields"}'

Example response

{
  "slot_id": "3381902442",
  "title": "Bake sale shift",
  "start": "2027-05-09T11:00:00-04:00",
  "location": "Gym entrance",
  "wanted": 5,
  "filled": 2
}

Duplicate sign-up

write

POST https://cotlet.dev/api/v1/signupgenius/duplicate_signup

Copies a sign-up, past or active, with its slots, and saves the copy as an unpublished draft under the new title. Nobody sees it and no one is told, so it runs without asking first. Check the dates on the copy before you publish it.

Parameters

Parameters: duplicate_signup
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
title required string Title of the copy.
group_id string Assign the copy to another group.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/duplicate_signup \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2","title":"title"}'
Python
result = client.call("signupgenius", "duplicate_signup", {"signup_id":"signup_8c41d2","title":"title"})
Node.js
const result = await cotlet.call('signupgenius', 'duplicate_signup', {"signup_id":"signup_8c41d2","title":"title"});
CLI
cotlet call signupgenius duplicate_signup --data '{"signup_id":"signup_8c41d2","title":"title"}'

Example response

{
  "signup_id": "52014408",
  "title": "Teacher conferences 2027",
  "status": "draft",
  "copied_from": "48820917",
  "slots": 18
}

Publish sign-up

write Confirm

POST https://cotlet.dev/api/v1/signupgenius/publish_signup

Makes a draft visible to anyone with the link and returns that link. It does not email the group; use send_message for that. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: publish_signup
NameTypeDescription
signup_id required string Sign-up ID from list_signups.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/publish_signup \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2"}'
Python
result = client.call("signupgenius", "publish_signup", {"signup_id":"signup_8c41d2"})
Node.js
const result = await cotlet.call('signupgenius', 'publish_signup', {"signup_id":"signup_8c41d2"});
CLI
cotlet call signupgenius publish_signup --data '{"signup_id":"signup_8c41d2"}'

Example response

{
  "signup_id": "52014408",
  "status": "active",
  "url": "https://www.signupgenius.com/go/52014408"
}

Add participant

write Confirm

POST https://cotlet.dev/api/v1/signupgenius/add_participant

Signs a person up for a slot and returns the new participant ID. With send_confirmation on, they get a confirmation email. A full slot is refused. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: add_participant
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
slot_id required string Slot ID from get_signup.
first_name required string First name.
last_name required string Last name.
email string Email; leave out if the person has none.
send_confirmation boolean Send them a confirmation email. Default: true.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/add_participant \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","first_name":"first name","last_name":"last name"}'
Python
result = client.call("signupgenius", "add_participant", {"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","first_name":"first name","last_name":"last name"})
Node.js
const result = await cotlet.call('signupgenius', 'add_participant', {"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","first_name":"first name","last_name":"last name"});
CLI
cotlet call signupgenius add_participant --data '{"signup_id":"signup_8c41d2","slot_id":"slot_8c41d2","first_name":"first name","last_name":"last name"}'

Example response

{
  "participant_id": "771204601",
  "signup_id": "50463821",
  "slot_id": "3381902442",
  "first_name": "Maya",
  "last_name": "Chen",
  "confirmation_sent": true
}

Move participant

write Confirm

POST https://cotlet.dev/api/v1/signupgenius/move_participant

Moves one participant to a slot that still has room, on the same sign-up, and returns both slot IDs. With notify on, the participant gets an email about the change. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: move_participant
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
participant_id required string Participant ID from list_participants.
to_slot_id required string Target slot ID from get_signup.
notify boolean Email the participant about the change. Default: true.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/move_participant \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2","to_slot_id":"to_slot_8c41d2"}'
Python
result = client.call("signupgenius", "move_participant", {"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2","to_slot_id":"to_slot_8c41d2"})
Node.js
const result = await cotlet.call('signupgenius', 'move_participant', {"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2","to_slot_id":"to_slot_8c41d2"});
CLI
cotlet call signupgenius move_participant --data '{"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2","to_slot_id":"to_slot_8c41d2"}'

Example response

{
  "participant_id": "771204518",
  "from_slot_id": "3381902441",
  "to_slot_id": "3381902442",
  "notified": true
}

Remove participant

write Confirm

POST https://cotlet.dev/api/v1/signupgenius/remove_participant

Removes one participant from their slot, which frees the spot. With notify on, the participant gets an email. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: remove_participant
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
participant_id required string Participant ID from list_participants.
notify boolean Email the participant about the change. Default: true.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/remove_participant \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2"}'
Python
result = client.call("signupgenius", "remove_participant", {"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2"})
Node.js
const result = await cotlet.call('signupgenius', 'remove_participant', {"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2"});
CLI
cotlet call signupgenius remove_participant --data '{"signup_id":"signup_8c41d2","participant_id":"participant_8c41d2"}'

Example response

{
  "participant_id": "771204533",
  "slot_id": "3381902442",
  "removed": true,
  "notified": false
}

Send message

write Confirm

POST https://cotlet.dev/api/v1/signupgenius/send_message

Sends one email from your SignUpGenius account and returns how many people it went to. People without an email are skipped and counted. Assign the sign-up to a group so not_signed_up has a list to compare with. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_message
NameTypeDescription
signup_id required string Sign-up ID from list_signups.
recipients required enum all, signed_up or not_signed_up.
subject required string Email subject.
body required string Message text.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/send_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signup_id":"50471160","recipients":"not_signed_up","subject":"Book fair: 6 spots still open next week","body":"Hi all, we still need help on Friday 12 March: 2 spots at 10:00 and 3 at 14:00, plus 1 on Saturday at 9:00. Pick one at the sign-up link."}'
Python
result = client.call("signupgenius", "send_message", {"signup_id":"50471160","recipients":"not_signed_up","subject":"Book fair: 6 spots still open next week","body":"Hi all, we still need help on Friday 12 March: 2 spots at 10:00 and 3 at 14:00, plus 1 on Saturday at 9:00. Pick one at the sign-up link."})
Node.js
const result = await cotlet.call('signupgenius', 'send_message', {"signup_id":"50471160","recipients":"not_signed_up","subject":"Book fair: 6 spots still open next week","body":"Hi all, we still need help on Friday 12 March: 2 spots at 10:00 and 3 at 14:00, plus 1 on Saturday at 9:00. Pick one at the sign-up link."});
CLI
cotlet call signupgenius send_message --data '{"signup_id":"50471160","recipients":"not_signed_up","subject":"Book fair: 6 spots still open next week","body":"Hi all, we still need help on Friday 12 March: 2 spots at 10:00 and 3 at 14:00, plus 1 on Saturday at 9:00. Pick one at the sign-up link."}'

Example response

{
  "signup_id": "50463821",
  "recipients": "not_signed_up",
  "sent": 14,
  "skipped_no_email": 1
}

Add group member

write

POST https://cotlet.dev/api/v1/signupgenius/add_group_member

Adds one person to a group and returns the member ID. Nothing is sent to them, and you can remove them from the group in SignUpGenius, so it runs without asking first. One person per call.

Parameters

Parameters: add_group_member
NameTypeDescription
group_id required string Group ID from list_groups.
email required string Member email.
first_name string First name.
last_name string Last name.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/signupgenius/add_group_member \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group_8c41d2","email":"jane@example.com"}'
Python
result = client.call("signupgenius", "add_group_member", {"group_id":"group_8c41d2","email":"jane@example.com"})
Node.js
const result = await cotlet.call('signupgenius', 'add_group_member', {"group_id":"group_8c41d2","email":"jane@example.com"});
CLI
cotlet call signupgenius add_group_member --data '{"group_id":"group_8c41d2","email":"jane@example.com"}'

Example response

{
  "member_id": "6610090",
  "group_id": "9120571",
  "email": "ana@example.com",
  "added": true
}