HeyPeers API Documentation for Organizations

Overview

Welcome to the HeyPeers API documentation tailored specifically for organizations. This guide is designed to assist organizations in interacting seamlessly with the HeyPeers platform through a set of secure and robust API endpoints. Whether you're looking to manage user invitations, generate one-time login links, or access various other services, this guide will walk you through the necessary steps.

Obtaining the Access Key

Each organization is assigned a unique access key. The owner of the organization has the ability generate a key from the manage organization page.

Base URL

All URLs referenced in the documentation have the following base:

https://heypeers.com/api/v2

Use the staging URL for the testing environment.

Authentication

To access the organization's external API, you need to have an Access Key (24 digits) which you can get from the organization's admin. Using the access key you will generate an Authorization Token, which you will pass as authorization in headers and expire after one day.

Endpoint

• POST: /authenticate

Request Parameters

• Body:
  • access_key The Access Key of the organization

Response Format

• Success Response:

  • Status Code: 200 OK
  • Body

  {
    "token": "YOUR_JWT_TOKEN"
  }

• Error Response:

  • Status Code: 401 Unauthorized
  • Body

  {
    "error": "Invalid Access Key"
  }

Example Request

curl -X POST "https://heypeers.com/api/v2/authenticate" \
     -H "Content-Type: application/json" \
     -d '{"access_key": "YOUR_ACCESS_KEY"}'

User Creation and Invitation API

This API allows organizations to invite new users to join the HeyPeers platform. The API will check if the user already exists and if they have been previously invited by the same organization. If the user already exists and has not yet accepted the invitation, the API will return an existing invitation URL. For new users, it will generate an invitation URL and return it in the response.

Endpoint

• POST: /organizations/:id/invite_user

Request Parameters

• Header:
  • Authorization: Bearer [Your Access Token]
• Body
  • email: The email address of the user to be invited (Required)
  • first_name: First name of the user (Required)
  • last_name: Last name of the user (Required)

Response Format

• Success Response:
  • Status Code: 200 OK
  • Body

  {
    "success": "User invited successfully.",
    "user": {
      "id": "[UUID]",
      "email": "[email]",
      "first_name": "[first_name]",
      "last_name": "[last_name]",
      "invitation_url": "[invitation_url]"
    }
  }
• Error Response:
  • Status Code: 400 Bad Request
  • Body

  {
    "error": "[Error Message]"
  }

Example Request

curl -X POST "https://heypeers.com/api/v2/organizations/[Organization_ID]/invite_user" \
     -H "Authorization: Bearer [Your Access Token]" \
     -d "email=user@email.com&first_name=John&last_name=Doe"

One-Time Login Link API

This API endpoint allows organizations to generate a one-time login link for a specific user. This link can be used to authenticate the user into the HeyPeers platform without requiring them to input their credentials manually.

Important: The One-Time Login link will expire after 5 minutes.

Endpoint

• POST: /organizations/:id/users/:uuid/generate_otl_url

Request Parameters

• Header:
  • Authorization: Bearer [Your Access Token]
• Query Params
  • uuid: The UUID of the user for whom the one-time login link is generated (Required)

Response Format

• Success Response:
  • Status Code: 200 OK
  • Body

  {
    "success": "OTL link generated",
    "otl_url": "[Generated One-Time Login URL]"
  }
• Error Response:
  • Status Code: 400 Bad Request
  • Body

  {
    "error": "[Error Message]"
  }

Example Request

curl -X POST "https://heypeers.com/api/v2/organizations/[Organization_ID]/users/[User_UUID]/one_time_login_link" \
     -H "Authorization: Bearer [Your Access Token]"

Support

If you encounter any issues or have questions about API, please contact HeyPeers support at support@heypeers.com.