Create Sales Rep

This POST endpoint is used to create a new sales representative in the system. The request must include necessary sales rep details, including personal information, contact details, and company/customer assignments.

Endpoint

• URL: /api/salesRep
• Method: POST

Authentication

• Header: accessToken
• Type: Bearer Token
• Value: <ACCESS-TOKEN>

Request Headers

Header	Type	Description
Content-Type	string	Must be application/json.
accessToken	string	Access token for authentication. (required)

Request Body

The body of the request should be a JSON object containing the following sales rep details:

Field	Type	Description
firstName	string	The first name of the sales rep. (required)
lastName	string	The last name of the sales rep. (optional)
email	string	The email address of the sales rep. (required)
phoneNumber	string	The contact number of the sales rep. (optional)
status	string	The status of the sales rep (e.g., "active", "inactive"). (optional)
salesRepCompanies	array	Array of company assignments with customers and access type.
metaFields	array	Array of meta-information fields for the sales rep.

Sales Rep Companies Object (salesRepCompanies[])

This field defines which companies and customers the sales rep can access.

Field	Type	Description
company	string	Company ID that the sales rep is assigned to. (required)
customers	array	Array of customer IDs assigned to this sales rep. (required)
accessType	string	Type of access for this company. Valid values: "customer", "role", "all". Defaults to "customer" if not specified.

Important Validation:

• All customers must exist in the system
• Each customer must belong to the company specified in the same salesRepCompanies object
• If validation fails, the request will return an error

MetaFields Object (metaFields[])

Field	Type	Description
code	string	Code for the metafield.
value	mixed	Value of the metafield.

Sample Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "+1234567890",
  "salesRepCompanies": [
    {
      "company": "665434c100e82884676936b9",
      "customers": [
        "66a5023524b16685e42a1eda",
        "66a5023524b16685e42a1edb"
      ],
      "accessType": "customer"
    },
    {
      "company": "665434c100e82884676936ba",
      "customers": [
        "66a5023524b16685e42a1edc"
      ],
      "accessType": "role"
    }
  ],
  "metaFields": [
    {
      "code": "territory",
      "value": "Northeast"
    },
    {
      "code": "employee_id",
      "value": "EMP-12345"
    }
  ]
}

Response

• Status Code: 200 OK

Success Response Body

{
  "success": true,
  "message": "SalesRep created successfully",
  "data": {
    "id": "66a5023524b16685e42a1eda",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1234567890",
    "status": "invited",
    "verifiedEmail": false,
    "salesRepCompanies": [
      {
        "id": "665434c100e82884676936b9",
        "company": "665434c100e82884676936b9",
        "customers": [
          "66a5023524b16685e42a1eda",
          "66a5023524b16685e42a1edb"
        ],
        "accessType": "customer"
      }
    ],
    "metaFields": [
      {
        "id": "66a5023524b16685e42a1edf",
        "code": "territory",
        "value": "Northeast"
      }
    ],
    "createdBy": {
      "name": "API Name api",
      "type": "api"
    },
    "createdAt": "2024-07-27T14:20:37.573Z",
    "updatedAt": "2024-07-27T14:20:37.573Z"
  }
}

Success Response Structure

Field	Type	Description
success	boolean	Indicates if the request was successful.
message	string	Message indicating the result of the operation.
data	object	Contains details of the newly created sales rep.

Data Object (data)

Field	Type	Description
id	string	Unique identifier for the sales rep.
email	string	Email address of the sales rep.
firstName	string	First name of the sales rep.
lastName	string	Last name of the sales rep.
phoneNumber	string	Contact number of the sales rep.
status	string	Current status (active
verifiedEmail	boolean	Email verification status (false initially).
salesRepCompanies	array	Array of company assignments with IDs transformed.
metaFields	array	Additional metadata with generated IDs.
createdBy	object	Information about who created the sales rep.
createdAt	string (ISO 8601)	Timestamp of when the sales rep was created.
updatedAt	string (ISO 8601)	Timestamp of the last update.

Error Responses

Status Code	Description
400 Bad Request	Invalid data, missing required fields, or validation errors.
401 Unauthorized	The access token is invalid or missing.
403 Forbidden	You do not have permission to create sales reps.
500 Internal Server Error	An error occurred on the server.