Skip to main content

Partner API

Usage​

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.partnerDirectory.approvePartner(...)

Tree-shakeable import​

import { getClient, authorize } from '@epilot/sdk/partner-directory'

const partnerDirectoryClient = getClient()
authorize(partnerDirectoryClient, () => '<token>')
const { data } = await partnerDirectoryClient.approvePartner(...)

Operations​

partners

partner_users

Schemas

approvePartner​

Approve partner request

POST /v1/partners/{id}/approve

const { data } = await client.approvePartner({
  id: '123e4567-e89b-12d3-a456-426614174000',
})
Response
{
  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
  "organization_id": "123",
  "created_at": "2022-02-08T04:44:32.246Z",
  "description": "Description",
  "company_name": "Company name",
  "invitation_token": "string",
  "invitation_email": "user@example.com",
  "email": "user@example.com",
  "owner_email": "user@example.com",
  "signed_up_email": "user@example.com",
  "partner_org_id": 123456,
  "status": "Pending"
}

rejectPartner​

Reject partner request

POST /v1/partners/{id}/reject

const { data } = await client.rejectPartner({
  id: '123e4567-e89b-12d3-a456-426614174000',
})
Response
{
  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
  "organization_id": "123",
  "created_at": "2022-02-08T04:44:32.246Z",
  "description": "Description",
  "company_name": "Company name",
  "invitation_token": "string",
  "invitation_email": "user@example.com",
  "email": "user@example.com",
  "owner_email": "user@example.com",
  "signed_up_email": "user@example.com",
  "partner_org_id": 123456,
  "status": "Pending"
}

searchAssignable​

searchAssignables

POST /v1/partners/assignables:search

const { data } = await client.searchAssignable(
  null,
  {
    q: '',
    from: 0,
    size: 25,
    org_ids: ['123'],
    portalUsersEntityIdScope: '',
    types: ['user', 'partner_user', 'partner_organization', 'ecp', 'group']
  },
)
Response
{
  "hits": 25,
  "results": [
    {
      "type": "user",
      "display_name": "Example User",
      "image_uri": {
        "original": "https://epilot-staging-user-content.s3.eu-central-1.amazonaws.com/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png",
        "thumbnail_32": "https://file.sls.epilot.io/v1/files/public/preview?w=32&h=32&key=/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png"
      },
      "org_id": "123",
      "created_at": "2022-02-08T04:44:32.246Z",
      "activated_at": "2022-02-08T04:44:32.246Z",
      "status": "Active",
      "user_id": "456",
      "email": "example@example.com"
    }
  ]
}

batchGetAssignable​

batchGet

POST /v1/partners/assignables:batchGet

const { data } = await client.batchGetAssignable(
  null,
  [
    {
      user_id: 'string',
      org_id: 'string',
      group_id: 'string'
    }
  ],
)
Response
{
  "hits": 25,
  "results": [
    {
      "type": "user",
      "display_name": "Example User",
      "image_uri": {
        "original": "https://epilot-staging-user-content.s3.eu-central-1.amazonaws.com/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png",
        "thumbnail_32": "https://file.sls.epilot.io/v1/files/public/preview?w=32&h=32&key=/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png"
      },
      "org_id": "123",
      "created_at": "2022-02-08T04:44:32.246Z",
      "activated_at": "2022-02-08T04:44:32.246Z",
      "status": "Active",
      "user_id": "456",
      "email": "example@example.com"
    }
  ]
}

getPartnerByToken​

Get partner by token

GET /v1/partner-directory/public/getPartnerByToken

const { data } = await client.getPartnerByToken({
  token: 'example',
})
Response
{
  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
  "organization_id": "123",
  "created_at": "2022-02-08T04:44:32.246Z",
  "description": "Description",
  "company_name": "Company name",
  "invitation_token": "string",
  "invitation_email": "user@example.com",
  "email": "user@example.com",
  "owner_email": "user@example.com",
  "signed_up_email": "user@example.com",
  "partner_org_id": 123456,
  "status": "Pending"
}

activatePartner​

Activate partner using an invite token

POST /v1/partner-directory/public/activate

const { data } = await client.activatePartner(
  {
    token: 'example',
  },
  {
    company_name: 'Company name',
    signed_up_email: 'user@example.com',
    organization_id: 'string'
  },
)

searchGeolocationForText​

Converts a given string, in the format of an address, to geo-location latitude and longitude

POST /v1/geolocation/text:search

const { data } = await client.searchGeolocationForText(
  null,
  {
    address: 'Auweg 1, 93055 Regensburg, DE'
  },
)
Response
{
  "lat": 49.013,
  "lng": 12.101,
  "addressLabel": "string",
  "relevance": 0
}

invitePartnerV2​

Invite a partner into collaboration. It will send an email to partner and ask to join into collaboration

POST /v2/partners/{id}/invite

const { data } = await client.invitePartnerV2(
  {
    id: '123e4567-e89b-12d3-a456-426614174000',
  },
  {
    language: 'en'
  },
)
Response
{
  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
  "organization_id": "123",
  "created_at": "2022-02-08T04:44:32.246Z",
  "description": "Description",
  "company_name": "Company name",
  "invitation_token": "string",
  "invitation_email": "user@example.com",
  "email": "user@example.com",
  "owner_email": "user@example.com",
  "signed_up_email": "user@example.com",
  "partner_org_id": 123456,
  "status": "Pending"
}

getPartnerUsers​

Get all users for a partner organization with their roles

GET /v2/partners/{orgId}/users

const { data } = await client.getPartnerUsers({
  orgId: 'example',
})
Response
{
  "results": [
    {
      "id": "456",
      "name": "John Doe",
      "email": "user@example.com",
      "status": "Active",
      "image": {
        "original": "https://example.com/path",
        "thumbnail_32": "https://example.com/path"
      },
      "roles": [
        {
          "id": "role-123",
          "slug": "admin",
          "name": "Administrator"
        }
      ]
    }
  ]
}

createPartnerUser​

Create a new user in a partner organization

POST /v2/partners/{orgId}/users

const { data } = await client.createPartnerUser(
  {
    orgId: 'example',
  },
  {
    email: 'user@example.com',
    language: 'en',
    roles: ['role-123', 'role-456']
  },
)
Response
{
  "id": "456",
  "email": "user@example.com",
  "display_name": "John Doe",
  "status": "Active"
}

deletePartnerUser​

Delete a user from a partner organization

DELETE /v2/partners/{orgId}/users/{userId}

const { data } = await client.deletePartnerUser({
  orgId: 'example',
  userId: 'example',
})
Response
{}

getPartnerRoles​

Get all roles for a partner organization

GET /v2/partners/{orgId}/roles

const { data } = await client.getPartnerRoles({
  orgId: 'example',
})
Response
{
  "results": [
    {
      "id": "role-123",
      "slug": "admin",
      "name": "Administrator",
      "type": "share_role"
    }
  ]
}

createPartnerRole​

Create a role for a partner organization

POST /v2/partners/{orgId}/roles

const { data } = await client.createPartnerRole(
  {
    orgId: 'example',
  },
  {
    name: 'Partner Admin',
    slug: 'partner_admin',
    grants: [
      {
        action: 'entity-read',
        resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947',
        effect: 'allow',
        conditions: [
          {
            attribute: 'workflows.primary.task_name',
            operation: 'equals',
            values: ['Qualification']
          }
        ],
        dependencies: [
          {
            action: 'entity-read',
            resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947',
            effect: 'allow',
            conditions: [
              {
                attribute: 'workflows.primary.task_name',
                operation: 'equals',
                values: ['Qualification']
              }
            ]
          }
        ]
      }
    ]
  },
)
Response
{
  "id": "role-123",
  "slug": "admin",
  "name": "Administrator",
  "type": "share_role"
}

updatePartnerRole​

Update a role for a partner organization

PUT /v2/partners/{orgId}/roles/{roleId}

const { data } = await client.updatePartnerRole(
  {
    orgId: 'example',
    roleId: 'example',
  },
  {
    grants: [
      {
        action: 'entity-read',
        resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947',
        effect: 'allow',
        conditions: [
          {
            attribute: 'workflows.primary.task_name',
            operation: 'equals',
            values: ['Qualification']
          }
        ],
        dependencies: [
          {
            action: 'entity-read',
            resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947',
            effect: 'allow',
            conditions: [
              {
                attribute: 'workflows.primary.task_name',
                operation: 'equals',
                values: ['Qualification']
              }
            ]
          }
        ]
      }
    ],
    id: '123:owner',
    name: 'Owner',
    slug: 'owner'
  },
)
Response
{
  "id": "role-123",
  "slug": "admin",
  "name": "Administrator",
  "type": "share_role"
}

assignPartnerUserRoles​

Assign roles to a user in a partner organization

POST /v2/partners/{orgId}/users/{userId}/roles

const { data } = await client.assignPartnerUserRoles(
  {
    orgId: 'example',
    userId: 'example',
  },
  {
    roleIds: ['role-123', 'role-456']
  },
)
Response
{
  "results": [
    {
      "roleId": "string",
      "success": true,
      "data": {},
      "error": {}
    }
  ]
}

unassignPartnerUserRoles​

Unassign roles from a user in a partner organization

DELETE /v2/partners/{orgId}/users/{userId}/roles

const { data } = await client.unassignPartnerUserRoles(
  {
    orgId: 'example',
    userId: 'example',
  },
  {
    roleIds: ['role-123', 'role-456']
  },
)
Response
{
  "results": [
    {
      "roleId": "string",
      "success": true,
      "data": {},
      "error": {}
    }
  ]
}

Schemas​

InviteToken​

type InviteToken = string

Partner​

type Partner = {
  id?: string
  organization_id?: string
  created_at?: string
  description?: string
  company_name?: string
  invitation_token?: string
  invitation_email?: string // email
  email?: string // email
  owner_email?: string // email
  signed_up_email?: string // email
  partner_org_id?: string
  status?: "Pending" | "Request" | "Deleted" | "Invited" | "Rejected"
}

PartnerId​

type PartnerId = string

OrganizationId​

type OrganizationId = string

ActivatePartnerPayload​

type ActivatePartnerPayload = {
  company_name?: string
  signed_up_email: string // email
  organization_id: string
}

PartnerInvitationPayload​

type PartnerInvitationPayload = {
  language?: "en" | "de"
}

Assignable​

type Assignable = {
  type: "user"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  user_id?: string
  email?: string
} | {
  type: "partner_user"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  partner_id?: string
  user_id?: string
  email?: string
} | {
  type: "partner_organization"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  partner_id: string
  email?: string
  geolocations?: Array<{
    address?: {
      street?: { ... }
      street_number?: { ... }
      city?: { ... }
      postal_code?: { ... }
      country?: { ... }
    }
    lat: number
    lng: number
    addressLabel?: string
    relevance?: number
  }>
  phone?: string
  activity_radius?: number
} | {
  type: "ecp"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  user_id: string
  email?: string
} | {
  type: string
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  group_id?: string
}

BaseAssignable​

type BaseAssignable = {
  type: string
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
}

AssignableUser​

type AssignableUser = {
  type: "user"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  user_id?: string
  email?: string
}

AssignablePartnerUser​

type AssignablePartnerUser = {
  type: "partner_user"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  partner_id?: string
  user_id?: string
  email?: string
}

AssignableGroup​

type AssignableGroup = {
  type: string
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  group_id?: string
}

AssignableOrganization​

type AssignableOrganization = {
  type: "partner_organization"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  partner_id: string
  email?: string
  geolocations?: Array<{
    address?: {
      street?: { ... }
      street_number?: { ... }
      city?: { ... }
      postal_code?: { ... }
      country?: { ... }
    }
    lat: number
    lng: number
    addressLabel?: string
    relevance?: number
  }>
  phone?: string
  activity_radius?: number
}

AssignableEcpPlaceholder​

type AssignableEcpPlaceholder = {
  type: "ecp"
  display_name: string
  image_uri?: {
    original: string // uri
    thumbnail_32?: string // uri
  }
  org_id: string
  created_at?: string
  activated_at?: string
  status?: "Active" | "Pending" | "Deactivated" | "Deleted"
  user_id: string
  email?: string
}

SearchGeolocation​

type SearchGeolocation = {
  address: string
}

Geolocation​

type Geolocation = {
  lat: number
  lng: number
  addressLabel?: string
  relevance?: number
}

Address​

type Address = {
  street?: string
  street_number?: string
  city?: string
  postal_code?: string
  country?: string
}

AddressGeolocation​

type AddressGeolocation = {
  address?: {
    street?: string
    street_number?: string
    city?: string
    postal_code?: string
    country?: string
  }
  lat: number
  lng: number
  addressLabel?: string
  relevance?: number
}

PartnerUser​

type PartnerUser = {
  id: string
  name?: string
  email: string // email
  status: string
  image?: {
    original?: string // uri
    thumbnail_32?: string // uri
  }
  roles: Array<{
    id: string
    slug: string
    name: string
  }>
}

CreatePartnerUserPayload​

type CreatePartnerUserPayload = {
  email: string // email
  language?: "en" | "de"
  roles?: string[]
}

CreatePartnerRolePayload​

type CreatePartnerRolePayload = {
  name: string
  slug: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
    dependencies?: Array<{
      action: { ... }
      resource?: { ... }
      effect?: { ... }
      conditions?: { ... }
    }>
  }>
}

UpdatePartnerRolePayload​

type UpdatePartnerRolePayload = {
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  id?: string
  name: string
  slug: string
}

Grant​

type Grant = {
  action: string
  resource?: string
  effect?: "allow" | "deny"
  conditions?: object[]
}

GrantWithDependencies​

type GrantWithDependencies = {
  action: string
  resource?: string
  effect?: "allow" | "deny"
  conditions?: object[]
  dependencies?: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

GrantCondition​

type GrantCondition = object

EqualsCondition​

Check if attribute equals to any of the values

type EqualsCondition = {
  attribute: string
  operation: "equals"
  values: unknown[]
}

RoleId​

Format: <organization_id>:<slug>

type RoleId = string

BaseRoleForCreate​

type BaseRoleForCreate = {
  id?: string
  name: string
  slug: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

PartnerRole​

type PartnerRole = {
  id: string
  slug: string
  name: string
  type?: string
}

AssignRolesPayload​

type AssignRolesPayload = {
  roleIds: string[]
}

User​

type User = {
  id?: string
  email?: string // email
  display_name?: string
  status?: string
}