NAV -image
bash javascript php

Introduction

Small API for CRM system to manage customers

This documentation aims to provide all the information you need to work with our API.

Base URL

[YOUR APP URL]

Authenticating requests

Authenticate requests to this API's endpoints by sending an Authorization header with the value "Bearer {TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by authorizing via Github OAuth2 Provider.

Customer endpoint

Endpoint used to manage CRM customers.

Get list of customers

requires authentication

Example request:

curl -X GET \
    -G "[YOUR APP URL]/api/v1/customers?page=1&perPage=16" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/customers"
);

let params = {
    "page": "1",
    "perPage": "16",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    '[YOUR APP URL]/api/v1/customers',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page'=> '1',
            'perPage'=> '16',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "data": [
        {
            "id": 1,
            "name": "name 1",
            "surname": "surname",
            "photoUrl": null,
            "created_by": {
                "id": 1,
                "email": "tagils@mail.ru",
                "username": "Fecony",
                "is_admin": true
            },
            "updated_by": {
                "id": 1,
                "email": "tagils@mail.ru",
                "username": "Fecony",
                "is_admin": true
            },
            "created_at": "2021-05-30 11:11:06",
            "updated_at": "2021-05-30 11:25:12"
        }
    ],
    "links": {
        "first": "http:\/\/theam_crm.test\/api\/v1\/customers?page=1",
        "last": "http:\/\/theam_crm.test\/api\/v1\/customers?page=3",
        "prev": null,
        "next": "http:\/\/theam_crm.test\/api\/v1\/customers?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "http:\/\/theam_crm.test\/api\/v1\/customers?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "http:\/\/theam_crm.test\/api\/v1\/customers?page=2",
                "label": "2",
                "active": false
            },
            {
                "url": "http:\/\/theam_crm.test\/api\/v1\/customers?page=3",
                "label": "3",
                "active": false
            },
            {
                "url": "http:\/\/theam_crm.test\/api\/v1\/customers?page=2",
                "label": "Next »",
                "active": false
            }
        ],
        "path": "http:\/\/theam_crm.test\/api\/v1\/customers",
        "per_page": "3",
        "to": 3,
        "total": 7
    }
}

Request   

GET api/v1/customers

Query Parameters

page  int optional  
Page number to return.

perPage  int optional  
Number of items to return in a page.

Create new customer

requires authentication

Example request:

curl -X POST \
    "[YOUR APP URL]/api/v1/customers" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"name":"Example name","surname":"Example surname","photo_id":"1"}'

const url = new URL(
    "[YOUR APP URL]/api/v1/customers"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Example name",
    "surname": "Example surname",
    "photo_id": "1"
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    '[YOUR APP URL]/api/v1/customers',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Example name',
            'surname' => 'Example surname',
            'photo_id' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (422, error):

{
    "message": "The given data was invalid.",
    "errors": {
        "name": [
            "The name field is required."
        ],
        "surname": [
            "The surname field is required."
        ]
    }
}

Example response (200):

{
    "data": {
        "id": null,
        "name": "Ofelia",
        "surname": "Hammes",
        "photoUrl": null,
        "created_by": {
            "id": 3,
            "email": "example@example.com",
            "username": "GithubUser",
            "is_admin": false
        },
        "updated_by": {
            "id": 1,
            "email": "tagils@mail.ru",
            "username": "Fecony",
            "is_admin": true
        },
        "created_at": "",
        "updated_at": ""
    }
}

Request   

POST api/v1/customers

Body Parameters

name  string  
Customer name.

surname  string  
Customer surname.

photo_id  string optional  
Photo id.

Get customer by id

requires authentication

Example request:

curl -X GET \
    -G "[YOUR APP URL]/api/v1/customers/17" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/customers/17"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    '[YOUR APP URL]/api/v1/customers/17',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (404, not found):

{
    "error": "Resource not found"
}

Example response (200):

{
    "data": {
        "id": null,
        "name": "Cristopher",
        "surname": "Hansen",
        "photoUrl": null,
        "created_by": {
            "id": 2,
            "email": "example@mail.ru",
            "username": "Test user",
            "is_admin": false
        },
        "updated_by": {
            "id": 1,
            "email": "tagils@mail.ru",
            "username": "Fecony",
            "is_admin": true
        },
        "created_at": "",
        "updated_at": ""
    }
}

Request   

GET api/v1/customers/{customer}

URL Parameters

customer  integer  
Customer id to show.

Update customer

requires authentication

Example request:

curl -X PUT \
    "[YOUR APP URL]/api/v1/customers/9" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/customers/9"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->put(
    '[YOUR APP URL]/api/v1/customers/9',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (404, not found):

{
    "error": "Resource not found"
}

Example response (200):

{
    "data": {
        "id": null,
        "name": "Hosea",
        "surname": "Howell",
        "photoUrl": null,
        "created_by": {
            "id": 3,
            "email": "example@example.com",
            "username": "GithubUser",
            "is_admin": false
        },
        "updated_by": {
            "id": 3,
            "email": "example@example.com",
            "username": "GithubUser",
            "is_admin": false
        },
        "created_at": "",
        "updated_at": ""
    }
}

Request   

PUT api/v1/customers/{customer}

PATCH api/v1/customers/{customer}

URL Parameters

customer  integer  
Customer id to update.

Delete customer

requires authentication

Example request:

curl -X DELETE \
    "[YOUR APP URL]/api/v1/customers/19" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/customers/19"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    '[YOUR APP URL]/api/v1/customers/19',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, success):

<Empty response>

Example response (404, not found):

{
    "error": "Resource not found"
}

Request   

DELETE api/v1/customers/{customer}

URL Parameters

customer  integer  
Customer id to remove.

Github Authentication

api/v1/auth/github

Example request:

curl -X GET \
    -G "[YOUR APP URL]/api/v1/auth/github" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/auth/github"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    '[YOUR APP URL]/api/v1/auth/github',
    [
        'headers' => [
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "url": "https:\/\/github.com\/login\/oauth\/authorize?client_id=9e62a6dce2a56a57c82a&redirect_uri=http%3A%2F%2Ftheam_crm.test%2Fapi%2Fv1%2Fauth%2Fgithub%2Fcallback&scope=user%3Aemail&response_type=code"
}

Request   

GET api/v1/auth/github

api/v1/auth/github/callback

Example request:

curl -X GET \
    -G "[YOUR APP URL]/api/v1/auth/github/callback" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/auth/github/callback"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    '[YOUR APP URL]/api/v1/auth/github/callback',
    [
        'headers' => [
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "user": {
        "id": 1,
        "email": "example@example.com",
        "username": "Github username",
        "is_admin": false
    },
    "token": "BEARER TOKEN"
}

Request   

GET api/v1/auth/github/callback

Logout endpoint

Used to "logout" user.

Logout user

requires authentication

This endpoint will remove current user personal token

Example request:

curl -X DELETE \
    "[YOUR APP URL]/api/v1/logout" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/logout"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    '[YOUR APP URL]/api/v1/logout',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, success):

<Empty response>

Request   

DELETE api/v1/logout

Photos endpoint

Endpoint used to manage photos

Upload photo

requires authentication

Example request:

curl -X POST \
    "[YOUR APP URL]/api/v1/photos" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: multipart/form-data" \
    -H "Accept: application/json" \
    -F "photo=@/private/var/folders/4s/181dychs12vcg4nrjvpfx_gc0000gn/T/phptgVxFX" 
const url = new URL(
    "[YOUR APP URL]/api/v1/photos"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('photo', document.querySelector('input[name="photo"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    '[YOUR APP URL]/api/v1/photos',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'photo',
                'contents' => fopen('/private/var/folders/4s/181dychs12vcg4nrjvpfx_gc0000gn/T/phptgVxFX', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, success):


{
 "photo": {
  "name": "lpSHaesceD8_1622373059.jpg",
  "path": "public/photos/lpSHaesceD8_1622373059.jpg",
  "updated_at": "2021-05-30T11:10:59.000000Z",
  "created_at": "2021-05-30T11:10:59.000000Z",
  "id": 1
}

Example response (422, error):


{
 "message": "The given data was invalid.",
 "errors": {
  "photo": [
    "The photo must be a file of type: png, jpg, jpeg."
  ]
}

Request   

POST api/v1/photos

Body Parameters

photo  file  
The image.

Delete photo

requires authentication

Example request:

curl -X DELETE \
    "[YOUR APP URL]/api/v1/photos/13" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/photos/13"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    '[YOUR APP URL]/api/v1/photos/13',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, success):

<Empty response>

Example response (404, not found):

{
    "error": "Resource not found"
}

Request   

DELETE api/v1/photos/{photo}

URL Parameters

photo  integer  
Photo id to remove.

User endpoint

Endpoint used to manage CRM users.

Get list of users

requires authentication

Example request:

curl -X GET \
    -G "[YOUR APP URL]/api/v1/users?page=1&perPage=16" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/users"
);

let params = {
    "page": "1",
    "perPage": "16",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    '[YOUR APP URL]/api/v1/users',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page'=> '1',
            'perPage'=> '16',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "data": [
        {
            "id": 1,
            "email": "example@example.com",
            "username": "GithubUser",
            "is_admin": false,
            "created_at": "2021-05-30 14:20:18",
            "updated_at": "2021-05-30 14:20:49"
        }
    ],
    "links": {
        "first": "http:\/\/theam_crm.test\/api\/v1\/users?page=1",
        "last": "http:\/\/theam_crm.test\/api\/v1\/users?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "active": false
            },
            {
                "url": "http:\/\/theam_crm.test\/api\/v1\/users?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "active": false
            }
        ],
        "path": "http:\/\/theam_crm.test\/api\/v1\/users",
        "per_page": "3",
        "to": 3,
        "total": 3
    }
}

Request   

GET api/v1/users

Query Parameters

page  int optional  
Page number to return.

perPage  int optional  
Number of items to return in a page.

Create user

requires authentication

Example request:

curl -X POST \
    "[YOUR APP URL]/api/v1/users" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"email":"email@example.com","username":"Example github username"}'

const url = new URL(
    "[YOUR APP URL]/api/v1/users"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "email@example.com",
    "username": "Example github username"
}

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    '[YOUR APP URL]/api/v1/users',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
        'json' => [
            'email' => 'email@example.com',
            'username' => 'Example github username',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (422, error):

{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email field is required."
        ],
        "username": [
            "The username field is required."
        ]
    }
}

Example response (200):

{
    "data": {
        "id": 422,
        "email": "rkoepp@example.org",
        "username": "schmitt.alvis",
        "is_admin": null,
        "created_at": "2021-06-01 17:28:15",
        "updated_at": "2021-06-01 17:28:15"
    }
}

Request   

POST api/v1/users

Body Parameters

email  string  
User email The value must be a valid email address.

username  string  
User username.

Get user by id

requires authentication

Example request:

curl -X GET \
    -G "[YOUR APP URL]/api/v1/users/12" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/users/12"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    '[YOUR APP URL]/api/v1/users/12',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (404, not found):

{
    "error": "Resource not found"
}

Example response (200):

{
    "data": {
        "id": 423,
        "email": "frederique89@example.net",
        "username": "cecelia.harris",
        "is_admin": null,
        "created_at": "2021-06-01 17:28:15",
        "updated_at": "2021-06-01 17:28:15"
    }
}

Request   

GET api/v1/users/{user}

URL Parameters

user  integer  
User id to show.

Update user

requires authentication

Example request:

curl -X PUT \
    "[YOUR APP URL]/api/v1/users/7" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/users/7"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->put(
    '[YOUR APP URL]/api/v1/users/7',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (404, not found):

{
    "error": "Resource not found"
}

Example response (200):

{
    "data": {
        "id": 424,
        "email": "romaine.trantow@example.org",
        "username": "heller.river",
        "is_admin": null,
        "created_at": "2021-06-01 17:28:15",
        "updated_at": "2021-06-01 17:28:15"
    }
}

Request   

PUT api/v1/users/{user}

PATCH api/v1/users/{user}

URL Parameters

user  integer  
User id to update.

Delete user

requires authentication

Example request:

curl -X DELETE \
    "[YOUR APP URL]/api/v1/users/17" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/users/17"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    '[YOUR APP URL]/api/v1/users/17',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (204, success):

<Empty response>

Example response (404, not found):

{
    "error": "Resource not found"
}

Request   

DELETE api/v1/users/{user}

URL Parameters

user  integer  
User id to remove.

Toggle admin state

requires authentication

Example request:

curl -X PATCH \
    "[YOUR APP URL]/api/v1/users/12/toggle_admin" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL(
    "[YOUR APP URL]/api/v1/users/12/toggle_admin"
);

let headers = {
    "Authorization": "Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PATCH",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->patch(
    '[YOUR APP URL]/api/v1/users/12/toggle_admin',
    [
        'headers' => [
            'Authorization' => 'Bearer {TOKEN}',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (404, not found):

{
    "error": "Resource not found"
}

Example response (200):

{
    "data": {
        "id": 425,
        "email": "grant36@example.org",
        "username": "asia35",
        "is_admin": null,
        "created_at": "2021-06-01 17:28:15",
        "updated_at": "2021-06-01 17:28:15"
    }
}

Request   

PATCH api/v1/users/{user}/toggle_admin

URL Parameters

user  integer  
User id to toggle admin role.

bash javascript php