API Documentation

Dealer User

The Dealer User API allows users to manager users for dealers.

The Dealer User Resource

Properties

  • Name
    id
    Required
    Type
    integer
    Description

    Unique identifier for the dealer-user resource. This is not a dealer or user ID, but is the mapping ID.

  • Name
    dealer
    Required
    Type
    DealerResource
    Description
    • Name
      id
      Required
      Type
      integer
      Description

      ID of the dealer

    • Name
      name
      Required
      Type
      string
      Description

      User friendly name of the dealer

  • Name
    user
    Required
    Type
    UserResource
    Description
    • Name
      id
      Required
      Type
      integer
      Description

      ID of the user

    • Name
      name
      Required
      Type
      string
      Description

      Full name of the user

  • Name
    dates
    Required
    Type
    DatesResource
    Description
    • Name
      created_at
      Required
      Type
      datetime
      Description

      The date the user was added to the dealer, represented in YYYY-MM-DD HH:MM:SS format

    • Name
      updated_at
      Required
      Type
      datetime
      Description

      The date the users mapping was last updated, represented in YYYY-MM-DD HH:MM:SS format

    • Name
      deleted_at
      Required
      Type
      null | datetime
      Description

      The date the user was removed from the dealer, represented in YYYY-MM-DD HH:MM:SS format. If the user is not removed, this will be null

Dealer User Resource

{
  "id": 1,
  "dealer": {
    "id": 12935,
    "name": "Test Dealer"
  },
  "user": {
    "id": 79,
    "name": "Jane Doe"
  },
  "dates": {
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-02 12:00:00",
    "deleted_at": null,
  }
}

The Dealer User Roles Resource

Properties

  • Name
    id
    Required
    Type
    integer
    Description

    Unique identifier for the dealer-user resource. This is not a dealer or user ID, but is the mapping ID.

  • Name
    dealer_id
    Required
    Type
    integer
    Description
  • Name
    id
    Required
    Type
    integer
    Description

    ID of the dealer

  • Name
    user_id
    Required
    Type
    integer
    Description
  • Name
    id
    Required
    Type
    integer
    Description

    ID of the user

  • Name
    roles
    Required
    Type
    array<string>
    Description

    An array of role slugs attached to this dealer user

  • Name
    dates
    Required
    Type
    DatesResource
    Description
    • Name
      updated_at
      Required
      Type
      datetime
      Description

      The date the users roles were last updated, represented in YYYY-MM-DD HH:MM:SS format

Dealer User Resource

{
  "id": 1,
  "dealer_id": 12935,
  "user_id": 79,
  "roles": [
    "complaints-administrator",
    "reports-administrator",
  ],
  "dates": {
    "updated_at": "2024-01-02 12:00:00",
  }
}
GET/v2/dealers/:dealer_id/users

Search Dealer Users

The search dealer users endpoint uses the standard Search package from the SDK.

An array of Dealer User resources are returned. If no results are found, an empty collection is returned.

URL Parameters

  • Name
    dealer_id
    Required
    required
    Type
    integer
    Description

    The Dealer ID to return users from

Search Filters

  • Name
    filters.id.equals
    Required
    Type
    integer
    Description

    Match a single dealer user by ID

  • Name
    filters.id.in
    Required
    Type
    array<integer>
    Description

    Match dealer users by multiple IDs

  • Name
    filters.user_id.equals
    Required
    Type
    integer
    Description

    fetch all dealer users by a matching user ID

  • Name
    filters.user_id.in
    Required
    Type
    array<integer>
    Description

    Match multiple dealer users by an array of user IDs

  • Name
    filters.created_at.before_or_on
    Required
    Type
    datetime
    Description

    Match all dealer users that were attached before or on this datetime.

  • Name
    filters.created_at.after_or_on
    Required
    Type
    datetime
    Description

    Match all dealer users that were attached after or on this datetime.

  • Name
    filters.updated_at.before_or_on
    Required
    Type
    datetime
    Description

    Match all dealer users that were last updated before or on this datetime.

  • Name
    filters.updated_at.after_or_on
    Required
    Type
    datetime
    Description

    Match all dealer users that were last updated after or on this datetime.

  • Name
    filters.deleted_at.equals
    Required
    Type
    boolean
    Description

    If you want to only removed dealer users from results, provide true. If you only non-removed dealer users, provide false

Search Ordering

  • id
  • user_id
  • created_at
  • updated_at
  • deleted_at

Request

GET
/v2/dealers/:dealer_id/users
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;
use Compliance\Sdk\Search\Search;

private ApexV3SdkInterface $sdk;

$search = new Search();

$response = $this->sdk
  ->v2(new Machine())
  ->dealer(1)
  ->users()
  ->search($search);

Response

{
  "data": [
    {
      "id": 1,
      "dealer": {
        "id": 12935,
        "name": "Test Dealer"
      },
      "user": {
        "id": 79,
        "name": "Jane Doe"
      },
      "dates": {
        "created_at": "2024-01-01 00:00:00",
        "updated_at": "2024-01-02 12:00:00",
        "deleted_at": null,
      }
    }
  ]
}
POST/v2/dealers/:dealer_id/users

Attach User

Will attach a user to a dealer

URL Parameters

  • Name
    dealer_id
    Required
    required
    Type
    integer
    Description

    ID of the dealer to attach the user to

Payload

  • Name
    user_id
    Required
    required
    Type
    integer
    Description

    The user ID to attach to the dealer

Error Codes

Status Description
404 The dealer couldn't be found
404 The user couldn't be found
422 The data provided in the payload was invalid. See errors for more details.
409 The user isn't a valid user type to be attached to a dealer (for example, when trying to attach a customer user type to a dealer)

Request

POST
/v2/dealers/:dealer_id/users
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->dealer(1)
  ->users()
  ->attach(79);

Response

{
  "data": {
    "id": 1,
    "dealer": {
      "id": 1,
      "name": "Test Dealer"
    },
    "user": {
      "id": 79,
      "name": "Jane Doe"
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null,
    }
  }
}
GET/v2/dealers/:dealer_id/users/:user_id

Retrieve Dealer User

Will retrieve a single dealer user by the dealer and user ID

URL Parameters

  • Name
    dealer_id
    Required
    required
    Type
    integer
    Description

    ID of the dealer that the user to retrieve belongs to

  • Name
    user_id
    Required
    required
    Type
    integer
    Description

    ID of the user to retrieve from the dealer

Error Codes

Status Description
404 The requested dealer user could not be found.

Request

GET
/v2/dealers/:dealer_id/users/:user_id
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->dealer(1)
  ->user(79)
  ->get();

Response

{
  "data": {
    "id": 1,
    "dealer": {
      "id": 1,
      "name": "Test Dealer"
    },
    "user": {
      "id": 79,
      "name": "Jane Doe"
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null,
    }
  }
}
DELETE/v2/dealers/:dealer_id/users/:user_id

Detach user from dealer

Will attempt to remove the user from the dealer. This endpoint will only affect users attached to the dealer.

The API will return a successful response if the user is already not attached to , but won't update the deleted_at timestamp.

URL Parameters

  • Name
    dealer_id
    Required
    required
    Type
    integer
    Description

    ID of the dealer to remove the user from

  • Name
    user_id
    Required
    required
    Type
    integer
    Description

    ID of the role to delete

Error Codes

Status Description
404 The requested dealer user could not be found.

Request

DELETE
/v2/dealers/:dealer_id/users/:user_id
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->dealer(1)
  ->user(79);
  ->detach()

Response

{
  "data": {
    "id": 1,
    "dealer": {
      "id": 1,
      "name": "Test Dealer"
    },
    "user": {
      "id": 79,
      "name": "Jane Doe"
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null,
    }
  }
}
PUT/v2/dealers/:dealer_id/users/:user_id/roles

Assign Roles

Users can have zero or more roles, distinct from other dealers their in. For example, a user may be a complaints administrator for dealer A, but not for dealer B.

Historical roles are not persisted when this endpoint is called. All roles the user is to be assigned to for the given dealer must be provided within the request.

Any roles not within the payload will be removed from the user.

Any roles specified in the update request which dont exist will be silently ignored and not added

URL Parameters

  • Name
    dealer_id
    Required
    required
    Type
    integer
    Description

    ID of the dealer which the user belongs to

  • Name
    user_id
    Required
    required
    Type
    integer
    Description

    ID of the user to attach roles to

Payload

  • Name
    roles
    Required
    required
    Type
    array<string>
    Description

    An array of role slugs to attach to the dealer user

Error Codes

Status Description
404 The dealer couldn't be found
404 The user couldn't be found
404 The user is not attached to the dealer
422 The data provided in the payload was invalid. See errors for more details.

Request

PUT
/v2/dealers/:dealer_id/users/:user_id/roles
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->dealer(1)
  ->user(79)
  ->roles()
  ->attach([
    'complaints-administrator',
    'reports-administrator',
  ]);

Response

{
  "data": {
    "id": 1,
    "dealer_id": 12935,
    "user_id": 79,
    "roles": [
      "complaints-administrator",
      "reports-administrator",
    ],
    "dates": {
      "updated_at": "2024-01-02 12:00:00",
    }
  }
}
GET/v2/dealers/:dealer_id/users/:user_id/roles

Get Roles

Retrieve a list of all the role attached to the dealer user.

URL Parameters

  • Name
    dealer_id
    Required
    required
    Type
    integer
    Description

    ID of the dealer which the user belongs to

  • Name
    user_id
    Required
    required
    Type
    integer
    Description

    ID of the user to fetch roles for

Error Codes

Status Description
404 The dealer couldn't be found
404 The user couldn't be found
404 The user is not attached to the dealer

Request

GET
/v2/dealers/:dealer_id/users/:user_id/roles
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->dealer(1)
  ->user(79)
  ->roles()
  ->get()

Response

{
  "data": {
    "id": 1,
    "dealer_id": 12935,
    "user_id": 79,
    "roles": [
      "complaints-administrator",
      "reports-administrator",
    ],
    "dates": {
      "updated_at": "2024-01-02 12:00:00",
    }
  }
}