GFA GFAVIP Onboard Login

API Documentation

Documentation for AI Agents and Developers to integrate with the GFAVIP Onboarding Hub.

Authentication

All API requests must include the X-API-Key header.

curl -H "X-API-Key: YOUR_API_KEY" https://onboard.gfavip.com/api/v1/contacts

You can generate API keys in the Dashboard Settings (Team access required). A key's full value is shown once at creation and stored hashed — copy it then.

Scopes

  • read — required for GET endpoints.
  • write — required for POST/PATCH; write also grants read.

Errors

  • 401 missing/invalid API key · 403 insufficient scope
  • 400 invalid request (e.g. malformed email) · 409 duplicate email
  • profile_research must be a JSON object or null; strings, arrays, booleans, and numbers return 400.

Error responses are JSON: { "error": "message" }.

Base URL

https://onboard.gfavip.com/api/v1

Endpoints

GET /contacts List all contacts (leads).

Query Parameters

  • page (int, default: 1) - Page number
  • per_page (int, default: 20) - Items per page
  • email (string, optional) - Filter by exact email match

Response Example

{
  "contacts": [
    {
      "id": "uuid-string",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Inc",
      "email": "john@example.com",
      "status": "Cold",
      "source": "API",
      "tags": "vip, 2024",
      "website": "https://example.com",
      "job_title": "VP Partnerships",
      "phone": "+1 555 0100",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "x_url": "https://x.com/johndoe",
      "profile_photo_url": "https://cdn.example.com/johndoe.jpg",
      "location": "New York",
      "country": "USA",
      "custom_fields": {
        "tier": "vip"
      },
      "profile_research": {
        "summary": "Payments executive focused on LATAM expansion.",
        "signals": ["payments", "sponsor-fit"],
        "sources": [
          {
            "url": "https://example.com/profile",
            "title": "Public profile"
          }
        ]
      },
      "created_at": "2024-03-20T10:00:00"
    }
  ],
  "total": 100,
  "pages": 5,
  "current_page": 1
}
POST /contacts Create a new contact.

Body Parameters (JSON)

  • email (string, required) - Unique email address
  • first_name (string, optional)
  • last_name (string, optional)
  • company_name (string, optional)
  • status (string, default: 'Cold') - e.g., Cold, Warm, Qualified
  • source (string, default: 'API')
  • website (string, optional)
  • job_title (string, optional)
  • phone (string, optional)
  • linkedin_url (string, optional)
  • x_url (string, optional)
  • profile_photo_url (string, optional)
  • location (string, optional)
  • country (string, optional)
  • tags (string, optional) - Comma separated
  • notes (string, optional)
  • custom_fields (object, optional) - JSON object for extra data
  • profile_research (object, optional) - JSON object for AI or manual research

API-created contacts are not auto-queued for email validation in this phase. Manual and CSV contacts are queued by the browser flow.

Response Example (Abbreviated)

{
  "id": "new-uuid-string",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Inc",
  "email": "john@example.com",
  "status": "Cold",
  "source": "API",
  "tags": "vip, 2024",
  "website": "https://example.com",
  "job_title": "VP Partnerships",
  "phone": "+1 555 0100",
  "linkedin_url": "https://linkedin.com/in/johndoe",
  "x_url": "https://x.com/johndoe",
  "profile_photo_url": "https://cdn.example.com/johndoe.jpg",
  "location": "New York",
  "country": "USA",
  "profile_research": {
    "summary": "Payments executive focused on LATAM expansion.",
    "signals": ["payments", "sponsor-fit"]
  }
}
PATCH /contacts/<id> Update an existing contact.

Body Parameters (JSON)

Include only fields you want to update.

  • status
  • tags
  • notes
  • first_name
  • last_name
  • company_name
  • website
  • job_title
  • phone
  • linkedin_url
  • x_url
  • profile_photo_url
  • location
  • country
  • custom_fields
  • profile_research (object or null)
POST /contacts/<id>/comments Add a comment to a contact's timeline.

Body Parameters (JSON)

  • content (string, required) - The text content of the comment

Response Example

{
  "id": "comment-uuid",
  "message": "Comment added successfully",
  "created_at": "2024-03-20T10:05:00"
}
GET /contacts/<id>/comments Get comment history for a contact.

Response Example

{
  "comments": [
    {
      "id": "comment-uuid",
      "content": "Sent outreach email #1",
      "user_id": "user-uuid",
      "user_name": "Lead Gen Agent",
      "created_at": "2024-03-20T10:05:00"
    }
  ]
}

Are you sure?