GET /v1/projects/{id}

Get a project

Access

Authenticated

project:read

Cost

Free

Rate limit

120 / minute per account

Quota

None

A project with derived stats, its live linked shortlists, whether its intake context is locked, and any managed agents Vamo is running on it.

Path parameters

id string required

max 16 chars

Responses

200 The project
- id string required
  
  The project id.
- name string required
  
  The project name, usually the role being hired for.
- status string required
  
  Where the project stands.
- companyRef ProjectCompanyRef required
  
  The company this role hires for. Null only on projects created before companies existed.
  - subjectType string required
    
    What kind of company record this points at: a client company on this account, or the account’s own profile.
  - subjectId string required
    
    The id of that record.
- companyName string | null required
  
  That company’s display name, resolved for you. Null only when no printable name is on file.
- createdBy string | null required
  
  The member or key that created the project. Null when unknown.
- createdAt string required
  
  When the project was created, as an ISO 8601 instant.
- updatedAt string required
  
  When it last changed, as an ISO 8601 instant.
- candidateListId string | null required
  
  The shortlist holding this project’s candidates. Every project gets one at creation.
- managedAgents array of ProjectManagedAgent required
  
  Vamo-managed agents working this project. Empty on an ordinary project; a project can have any number.
  - id string required
    
    The managed agent id.
  - name string required
    
    The agent’s name.
  - status string required
    
    Where the agent stands on this project.
- stats object required
  
  Candidate, sequence and outreach counters for this project.
  - candidates integer required
    
    How many candidates are on this project.
  - sequences integer required
    
    How many outreach sequences are running for it.
  - contacted integer required
    
    Distinct people who have actually had at least one message sent to them on this project. Not the number of messages, and not the number scheduled.
  - replyRate number | null required
    
    Replies as a fraction of people contacted, 0 to 1. Null when nobody has been contacted yet, which is different from a rate of zero.
- shortlists array of object required
  
  Every shortlist linked to this project, including its candidate list.
  - shortlistId string required
    
    The linked shortlist id.
  - name string required
    
    The shortlist name.
  - kind string required
    
    What kind of shortlist it is.
- contextLocked boolean required
  
  True once the project’s intake was frozen. Informational only today: edits are no longer refused because of it.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
403 Missing project:read
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
404 No such project in this account
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.