Edara API v3: Sales Persons

Read the guide first: authentication, paging, errors, rate limits and the shared PagedResult, BatchResult and *Reference shapes.

• GET /v3/sales-persons: Lists sales persons.
• GET /v3/sales-persons/{id}: Gets a sales person by id.
• POST /v3/sales-persons: Creates a sales person.
• PUT /v3/sales-persons/{id}: Updates a sales person by id.
• PUT /v3/sales-persons/code/{code}: Updates a sales person by code.
• DELETE /v3/sales-persons/{id}: Deletes a sales person by id.
• DELETE /v3/sales-persons/code/{code}: Deletes a sales person by code.

Endpoints

GET /v3/sales-persons: Lists sales persons.

Operation GetSalesPersons · permission read:sales-person

Query string: GetSalesPersonsQuery

Responses: OK PagedResult<SalesPersonResponse>: Paged list of sales persons.

Notes

• code and name match partially (contains), while externalId must match exactly.
• updateDate returns sales persons created or updated strictly after the value.
• Filter values are trimmed. A blank filter is ignored.
• The list includes internal and external sales persons, and inactive ones too.
• Results are ordered by id.
• When nothing matches, or the offset is past the end, the response is 404, not an empty list. Treat that 404 as an empty result.

GET /v3/sales-persons/{id}: Gets a sales person by id.

Operation GetSalesPersonById · permission read:sales-person

Parameters

Responses: OK SalesPersonResponse: The sales person.

Notes

• Only internal sales persons are returned. An external sales person that the list endpoint returns gives 404 here, the same as an id that does not exist.
• Inactive sales persons are returned.

POST /v3/sales-persons: Creates a sales person.

Operation CreateSalesPerson · permission create:sales-person

Body: SalesPersonUpsertRequest

Responses: Created SalesPersonResponse: Sales person created.

Business errors (HTTP 409, match on errorCode):

• DupplicatedCode: Another sales person already uses the same code.
• DupplicatedName: Another sales person already uses the same name.

Notes

• code and externalId are optional, but if you send them they cannot be blank.
• A request without a body returns 400.
• If you omit code, the sales person is saved without a code. No code is generated, and any number of sales persons can have no code.
• A new sales person is always active and always internal. The supervisor flag, the external flag and tags are ignored on create and get their default values.
• A duplicate name returns 409 with errorCode DupplicatedName. A duplicate code returns 409 with errorCode DupplicatedCode.
• Special characters are removed from code and name when they are saved. The 201 response repeats what you sent, so it can show characters that were not stored.

PUT /v3/sales-persons/{id}: Updates a sales person by id.

Operation UpdateSalesPersonById · permission update:sales-person

Parameters

Body: SalesPersonUpsertRequest

Responses: OK SalesPersonResponse: The updated sales person.

Business errors (HTTP 409, match on errorCode):

• DupplicatedCode: Another sales person already uses the same code.
• DupplicatedName: Another sales person already uses the same name.

Notes

• Only internal sales persons can be updated. The id of an external sales person returns 404.
• This is a full replace for name, classificationCode and creditLimit. If you omit classificationCode it is cleared, and if you omit creditLimit it becomes 0.
• code is the exception: if you omit it or send it empty, the stored code is kept.
• externalId in the body is ignored without an error, so you cannot change it with this endpoint. isActive, the supervisor flag and tags also keep their stored values.
• A duplicate name or code returns 409 with errorCode DupplicatedName or DupplicatedCode.

PUT /v3/sales-persons/code/{code}: Updates a sales person by code.

Operation UpdateSalesPersonByCode · permission update:sales-person

Parameters

Body: SalesPersonUpsertRequest

Responses: OK SalesPersonResponse: The updated sales person.

Business errors (HTTP 409, match on errorCode):

• DupplicatedCode: Another sales person already uses the same code.
• DupplicatedName: Another sales person already uses the same name.

Notes

• The code in the path is trimmed and matched exactly, among internal sales persons only. No match returns 404.
• Apart from the lookup, this behaves like the update by id: it is a full replace for name, classificationCode and creditLimit, and externalId in the body is ignored.
• If the body code is omitted or empty, the sales person keeps the code from the path. A different body code renames the sales person.

DELETE /v3/sales-persons/{id}: Deletes a sales person by id.

Operation DeleteSalesPersonById · permission delete:sales-person

Parameters

Responses: NoContent: (not declared; read from the method body)

Business errors (HTTP 409, match on errorCode):

• ItemCannotDeleteItInUse: The sales person is referenced by existing documents or related records.

Notes

• The delete is permanent, and the sales person's supervision links are removed with it. Success returns 204.
• Only internal sales persons can be deleted. The id of an external sales person returns 404.
• A sales person that is still referenced cannot be deleted and returns 409 with errorCode ItemCannotDeleteItInUse.
• References that block the delete include sales documents, quotes, targets, users linked to the sales person, work orders, physical counts, customer assignments and incentive assignments.

DELETE /v3/sales-persons/code/{code}: Deletes a sales person by code.

Operation DeleteSalesPersonByCode · permission delete:sales-person

Parameters

Responses: NoContent: (not declared; read from the method body)

Business errors (HTTP 409, match on errorCode):

• ItemCannotDeleteItInUse: The sales person is referenced by existing documents or related records.

Notes

• The code in the path is trimmed and matched exactly, among internal sales persons only. No match returns 404.
• Apart from the lookup, this behaves like the delete by id. The delete is permanent, and a sales person that is still referenced returns 409 with errorCode ItemCannotDeleteItInUse.

Types

SalesPersonResponse

Response describing a sales person.