POST api/v1/Users/{id}/UserCards/ReplaceCardIfExists

Adds a Card to an existing User. If the card is assigned to another user un-assigns it first. Returns Success/Error code plus primary key of UserCard entry made.

Request Information

URI Parameters

Name	Description	Type	Additional information
id		string	None.

Body Parameters

ReplaceUserCardIfExistsViewModel

Name	Description	Type	Additional information
UserId	Required: The PK of the existing User that you want to add the card to.	globally unique identifier	None.
CardId	Optional: The PK of an existing card that you want to assign to the User. Retrieve possible values from /Card/GetAllCards. If null, CardType, CardACSystem, InternalCardNumber, ExternalCardNumber and Facility code are required.	globally unique identifier	None.
CardType	Conditional: If CardId is null, this is required. Represents the type of card being added dynamically. Retrieve possible values from /Card/GetAllCardTypes	integer	None.
CardACSystemId	Conditional: If CardId is null, this is required. Represents the Access Control System of the card being added dynamically. Retrieve possible values from /ACSystem/GetAllSystems	globally unique identifier	None.
InternalCardNumber	Conditional: If CardId is null, this is required. Represents the internal/encoded number of the card being added dynamically.	integer	None.
ExternalCardNumber	Conditional: If CardId is null, this is required. Represents the external number printed on the card being added dynamically.	string	None.
CardSerialNumber	Conditional: If CardType supports it, this is required. Represents the serial number of the smart card being added dynamically.	integer	None.
FacilityCode	Conditional: If CardType supports it, this is required. Represents the facility code of the smart card being added dynamically.	integer	None.
IssueCode	Conditional: If CardType supports it, this is required. Represents the issue code of the smart card being added dynamically.	integer	None.
PIN	Optional: The PIN that the User may use in conjunction with this Card for Card + PIN mode or for when Readers are in PIN mode only.	string	None.
EnforceOccupancySystem	Optional: Requests to verify if the CardACSystemId matches the system the User's Occupancy belongs to	boolean	None.
CardActivationStartDateTime	Optional: Date and time of the card activation	date	None.
CardDeactivationStartDateTime	Optional: Date and time of the card de-activation	date	None.
CardUserFlags	Card User Flags	CardUserFlags	None.

Request Formats

application/json, text/json

Sample:

{
  "UserId": "0142cf90-cd69-4ff7-a31f-b4ab3840e684",
  "CardId": "79e66d24-a846-4a74-81fc-a2e5577c6094",
  "CardType": 2,
  "CardACSystemId": "cf2784f3-25c6-4230-9e3d-ccbe4e8b32e9",
  "InternalCardNumber": 3,
  "ExternalCardNumber": "sample string 4",
  "CardSerialNumber": 1,
  "FacilityCode": 1,
  "IssueCode": 1,
  "PIN": "sample string 5",
  "EnforceOccupancySystem": true,
  "CardActivationStartDateTime": "2026-03-02T13:41:23.7323837+00:00",
  "CardDeactivationStartDateTime": "2026-03-02T13:41:23.7323837+00:00",
  "CardUserFlags": 1
}

application/xml, text/xml

Sample:

<ReplaceUserCardIfExistsViewModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/APIWebRole.Controllers">
  <CardACSystemId>cf2784f3-25c6-4230-9e3d-ccbe4e8b32e9</CardACSystemId>
  <CardActivationStartDateTime>2026-03-02T13:41:23.7323837+00:00</CardActivationStartDateTime>
  <CardDeactivationStartDateTime>2026-03-02T13:41:23.7323837+00:00</CardDeactivationStartDateTime>
  <CardId>79e66d24-a846-4a74-81fc-a2e5577c6094</CardId>
  <CardSerialNumber>1</CardSerialNumber>
  <CardType>2</CardType>
  <CardUserFlags>ActiveCardholderRecord</CardUserFlags>
  <EnforceOccupancySystem>true</EnforceOccupancySystem>
  <ExternalCardNumber>sample string 4</ExternalCardNumber>
  <FacilityCode>1</FacilityCode>
  <InternalCardNumber>3</InternalCardNumber>
  <IssueCode>1</IssueCode>
  <PIN>sample string 5</PIN>
  <UserId>0142cf90-cd69-4ff7-a31f-b4ab3840e684</UserId>
</ReplaceUserCardIfExistsViewModel>

application/x-www-form-urlencoded

Sample:

Sample not available.

Response Information

Resource Description

ReplaceCardIfExistsResult

Name	Description	Type	Additional information
PreviousUserId	Represents a UserId for a user the card previously belonged to	globally unique identifier	None.
CurrentUserId	Represents a UserId for a user the card has been assigned to	globally unique identifier	None.
ExternalCardNumber	Represents the serial number of the smart card being added dynamically	string	None.
InternalCardNumber	Represents the internal/encoded number of the card being added dynamically.	integer	None.
FacilityCode	Represents the facility code of the smart card being added dynamically.	integer	None.
CardType	Represents the type of card being added dynamically. Retrieve possible values from /Card/GetAllCardTypes	integer	None.
Value	Represents the PK value that was created as a result of an add	globally unique identifier	None.
ResultCode	Represents the result code	integer	None.
Description	Represents a description of the result code	string	None.

Response Formats

application/json, text/json

Sample:

{
  "PreviousUserId": "b6ea31a8-7175-4ca1-8a50-90a30e0ea0e9",
  "CurrentUserId": "62e55e10-4738-4b8b-b5bd-3dad09358b17",
  "ExternalCardNumber": "sample string 1",
  "InternalCardNumber": 1,
  "FacilityCode": 1,
  "CardType": 1,
  "Value": "5718f865-8c7a-4da2-b477-e036d42f882a",
  "ResultCode": 3,
  "Description": "sample string 4"
}

application/xml, text/xml

Sample:

<ReplaceCardIfExistsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/APIWebRole.Controllers">
  <Description>sample string 4</Description>
  <HttpStatusCode>Continue</HttpStatusCode>
  <ResultCode>3</ResultCode>
  <Value>5718f865-8c7a-4da2-b477-e036d42f882a</Value>
  <CardType>1</CardType>
  <CurrentUserId>62e55e10-4738-4b8b-b5bd-3dad09358b17</CurrentUserId>
  <ExternalCardNumber>sample string 1</ExternalCardNumber>
  <FacilityCode>1</FacilityCode>
  <InternalCardNumber>1</InternalCardNumber>
  <PreviousUserId>b6ea31a8-7175-4ca1-8a50-90a30e0ea0e9</PreviousUserId>
</ReplaceCardIfExistsResult>