Skip to main content

Organizations

API endpoints related to managing Organizations. The organization is the starting point of the AskBenny API: it represents your business entity and contains every related resource — Agents, Knowledge Bases, Call Logs, and SMS Logs.

Note: These endpoints require an API key scoped to the organization in the path. Requests made with an API key that belongs to a different organization return 401 Unauthorized.

List Organizations​

Retrieves the organizations linked to your API key.

GET /v1/organizations

Headers:

  • x-api-key (string, required): Your API key for authentication.

Response:

  • 200 OK: Organizations retrieved successfully. 
    {
      "message": "Successfully retrieved organization",
      "data": [
        {
          "id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
          "name": "Example Corp",
          "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4",
          "timezone": "America/Toronto",
          "createdAt": 1698407100000,
          "updatedAt": 1698410700000
        }
      ]
    }
  • 400 Bad Request: Invalid or expired API key.

Try it yourself​

GET/v1/organizations
Request URL: https://api.askbenny.ca/v1/organizations

Update Organization​

Updates details for an existing organization.

PATCH /v1/organizations/{organizationId}

Path Parameters:

  • organizationId (string, required): The unique identifier of the organization to update.

Headers:

  • Content-Type (string, required): Must be set to application/json.
  • x-api-key (string, required): Your API key for authentication.

Request Body:

{
  "name": "Example Solutions Inc.",
  "contact": {
    "phone": "+15553219876",
    "email": "contact@example.com",
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postalCode": "12345",
      "country": "US"
    }
  },
  "description": "A detailed description of the business",
  "imageUrl": "https://example.com/logo.png",
  "timezone": "America/Los_Angeles",
  "openingHours": ["Monday: 9:00 AM - 5:00 PM", "Tuesday: 9:00 AM - 5:00 PM"],
  "appointmentLinkEnabled": true,
  "appointmentLink": "https://example.com/book",
  "notificationSettings": {"email": true, "phone": true},
  "callForwardingEnabled": true,
  "callForwardingNumber": "+15551234567"
}

Response:

  • 200 OK: Organization updated successfully. The updated organization is returned in the body field. 
    {
      "message": "Updating organization asynchronously. Try fetching the organization by id: ChIJN1t_tDeuEmsRUsoyG83frY4 in a few seconds",
      "body": {
        "id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
        "name": "Example Corp",
        "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4", 
        "userId": "usr_123abc", 
        "description": "A detailed description of the business",
        "imageUrl": "https://example.com/logo.png",
        "timezone": "America/Toronto", 
        "appointmentLinkEnabled": true,
        "appointmentLink": "https://example.com/book",
        "notificationSettings": {"email": true, "phone": true},
        "callForwardingEnabled": true,
        "callForwardingNumber": "+15551234567",
        "twilioPhoneNumber": "+15553219876", // Assigned number
        "openingHours": ["Monday: 9:00 AM - 5:00 PM", "Tuesday: 9:00 AM - 5:00 PM"],
        "contact": {
          "phone": "+15553219876",
          "address": {
            "street": "123 Main St",
            "city": "Anytown",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
          }
        },
        "createdAt": 1698407100000,
        "updatedAt": 1698410700000
      }
    }
  • 400 Bad Request: Invalid input data, invalid API key, or call forwarding was enabled without a valid callForwardingNumber.
  • 404 Not Found: Organization with the specified organizationId not found.

Try it yourself​

PATCH/v1/organizations/{organizationId}
Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}

Get Organization by ID​

Retrieves details for a specific organization.

GET /v1/organizations/{organizationId}

Path Parameters:

  • organizationId (string, required): The unique identifier of the organization to retrieve. Note that API-created organizations will have IDs in the format placeId.

Headers:

  • x-api-key (string, required): Your API key for authentication.

Request Body:

None. This endpoint only requires the organization ID in the path and API key in the header.

Response:

  • 200 OK: Organization details retrieved successfully. 
    {
      "message": "Successfully retrieved organization",
      "data": {
        "id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
        "name": "Example Corp",
        "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4", 
        "userId": "usr_123abc", 
        "description": "A detailed description of the business",
        "imageUrl": "https://example.com/logo.png",
        "timezone": "America/Toronto", 
        "appointmentLinkEnabled": true,
        "appointmentLink": "https://example.com/book",
        "notificationSettings": {"email": true, "phone": true},
        "callForwardingEnabled": true,
        "callForwardingNumber": "+15551234567",
        "twilioPhoneNumber": "+15551234567", // Assigned number
        "openingHours": ["Monday: 9:00 AM - 5:00 PM", "Tuesday: 9:00 AM - 5:00 PM"],
        "contact": {
          "phone": "+15981234562",
          "address": {
            "street": "123 Main St",
            "city": "Anytown",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
          }
        },
        "createdAt": 1698407100000,
        "updatedAt": 1698410700000
      }
    }
  • 400 Bad Request: Invalid API key.
  • 404 Not Found: Organization with the specified organizationId not found.

Try it yourself​

GET/v1/organizations/{organizationId}
Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}

Additional Organization Features​

When working with organizations, the following features are available:

Appointment Booking​

Enable online appointment booking for your organization:

  • appointmentLinkEnabled (boolean): Set to true to enable appointment booking
  • appointmentLink (string): URL where customers can book appointments

Business Hours​

Provide your business hours to help Benny respond to availability questions:

  • openingHours (array of strings): Business operating hours in a structured format
  • timezone (string): Business timezone (default: "America/Toronto")

Notification Preferences​

Control how you receive notifications:

  • notificationSettings.email (boolean): Receive notifications via email
  • notificationSettings.phone (boolean): Receive notifications via phone

Call Forwarding​

Enable automated call forwarding when a caller requests to speak with a real human:

  • callForwardingEnabled (boolean): Set to true to enable call forwarding
  • callForwardingNumber (string): Phone number to forward calls to when a user requests to speak with a real human or a member of your team

These settings enable Benny to provide more accurate and helpful interactions with your customers.